A description
About Zero-runtime polymorphic component definitions for React
npm install @axa-ch/react-polymorphic-types[![Build Status][ci-image]][ci-url]
[![MIT License][license-image]][license-url]
[![NPM version][npm-version-image]][npm-url]
[![NPM downloads][npm-downloads-image]][npm-url]
react-polymorphic-types is a library that enables the creation of zero-runtime polymorphic component definitions in React.
When building design systems or reusable UI components in React, you may come across the need for polymorphic components. A polymorphic component is a versatile component that can render different underlying HTML elements or custom components based on a prop.
A React polymorphic component provides flexibility to the consumer, allowing them to specify the desired element or component type to be rendered using a prop.
For example, let's consider a polymorphic heading component:
``tsx
import { createElement, ElementType, PropsWithChildren, ComponentProps } from 'react';
// Define the props for the polymorphic heading component
type HeadingProps
{
as?: T;
} & ComponentProps
>;
// Define the polymorphic heading component
export const Heading =
createElement(as, rest, children);
`
In the above example, the Heading component can render different heading levels (h1, h2, h3, etc.) based on the as prop. By default, it renders as an h1 element.
You can use the Heading component in your application like this:
` A descriptiontsx`
const App = () => (
);
In this case, the same Heading component is used to render two different semantic tags, h1 and h2, allowing you to control the heading level and maintain consistency across your application.
Polymorphic components provide an elegant solution for building flexible and reusable UI components in React, enabling you to create a cohesive design system with consistent semantics.
The use of the as attribute can become complex when adding constraints to your rendered markup or when using third-party components. Declaring polymorphic types for each component can also be a tedious task that you may want to abstract.
With @axa-ch/react-polymorphic-types, you can easily add constraints to your polymorphic React components and avoid redundant type definitions.
Install the TypeScript types via npm:
`shell`
npm i @axa-ch/react-polymorphic-types -D
The following recipes provide a starting point for creating polymorphic components. You can copy and modify them according to your requirements.
Basic Example
This example showcases a simple polymorphic heading element. It allows you to independently define its size and markup using props.
`tsx
import { ComponentPropsWithoutRef, createElement, ElementType } from 'react';
import { PolymorphicProps } from '@axa-ch/react-polymorphic-types';
// Default HTML element if the "as" prop is not provided
export const HeadingDefaultElement: ElementType = 'h1';
// List of allowed HTML elements that can be passed via the "as" prop
export type HeadingAllowedElements = typeof HeadingDefaultElement | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
export type HeadingSizes = 1 | 2 | 3 | 4 | 5 | 6;
// Component-specific props
export type HeadingOwnProps
size?: HeadingSizes;
};
// Extend own props with others inherited from the underlying element type
// Own props take precedence over the inherited ones
export type HeadingProps
HeadingOwnProps
T,
HeadingAllowedElements
>;
export const Heading =
as = HeadingDefaultElement,
size,
className,
children,
...rest
}: HeadingProps
createElement(
as,
{
...rest,
className: ${className} size-${size || 1},`
},
children,
);
You can use the Heading component in your application as shown below:
`tsx
const App = () => (
size={2}
>
My Main Headline
size={5}
>
A Subtitle
{/ The following component will throw a TypeScript error because 'div' elements are not allowed here /}
size={5}
>
A Subtitle
A description
Basic Example with Ref
This example is similar to the previous one, but it also allows the use of React refs.
`tsx
import { ComponentPropsWithoutRef, createElement, ElementType, forwardRef } from 'react';
import { PolymorphicProps, PolymorphicForwardedRef } from '@axa-ch/react-polymorphic-types';// Default HTML element if the "as" prop is not provided
export const HeadingDefaultElement: ElementType = 'h1';
// List of allowed HTML elements that can be passed via the "as" prop
export type HeadingAllowedElements = typeof HeadingDefaultElement | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
export type HeadingSizes = 1 | 2 | 3 | 4 | 5 | 6;
// Component-specific props
export type HeadingOwnProps = ComponentPropsWithoutRef & {
size?: HeadingSizes;
};
// Extend own props with others inherited from the underlying element type
// Own props take precedence over the inherited ones
export type HeadingProps = PolymorphicProps<
HeadingOwnProps,
T,
HeadingAllowedElements
>;
const HeadingInner = (
{ as = HeadingDefaultElement, size, className, children, ...rest }: HeaadingProps,
// notice the use of the PolymorphicForwardedRef type here
ref: PolymorphicForwardedRef,
) =>
createElement(
as,
{
...rest,
ref,
className:
${className} size-${size || 1},
},
children,
);// Forward refs with generics is tricky
// see also https://fettblog.eu/typescript-react-generic-forward-refs/
export const Heading = forwardRef(HeadingInner) as unknown as (
props: HeadingProps & { ref?: PolymorphicForwardedRef },
) => ReturnType;
`Using the
@axa-ch/react-polymorphic-types types will allow you to automatically infer the proper ref DOM node.`tsx
const App = () => {
// The use of HTMLHeadingElement type is safe
const ref = useRef(null); return (
ref={ref}
as='h2'
/>
);
};
`
React 19 Example with Ref
This example is similar to the previous one, but with React 19 the refs forwarding got much easier
`tsx
import { ComponentPropsWithoutRef, createElement, ElementType, forwardRef } from 'react';
import { PolymorphicProps, PolymorphicForwardedRef } from '@axa-ch/react-polymorphic-types';// Default HTML element if the "as" prop is not provided
export const HeadingDefaultElement: ElementType = 'h1';
// List of allowed HTML elements that can be passed via the "as" prop
export type HeadingAllowedElements = typeof HeadingDefaultElement | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
export type HeadingSizes = 1 | 2 | 3 | 4 | 5 | 6;
// Component-specific props
export type HeadingOwnProps = ComponentPropsWithoutRef & {
size?: HeadingSizes;
ref?: PolymorphicForwardedRef;
};
// Extend own props with others inherited from the underlying element type
// Own props take precedence over the inherited ones
export type HeadingProps = PolymorphicProps<
HeadingOwnProps,
T,
HeadingAllowedElements
>;
const Heading = ({
as = HeadingDefaultElement,
size,
className,
ref,
children,
...rest
}: HeadingProps) =>
createElement(
as,
{
...rest,
ref,
className:
${className} size-${size || 1},
},
children,
);
`Using the
@axa-ch/react-polymorphic-types types will allow you to automatically infer the proper ref DOM node.`tsx
const App = () => {
// The use of HTMLHeadingElement type is safe
const ref = useRef(null); return (
ref={ref}
as='h2'
/>
);
};
`
Basic Example with Memo
This example shows the use of React.memo with a polymorphic component.
`tsx
import { ComponentPropsWithoutRef, createElement, ElementType, memo } from 'react';
import { PolymorphicProps } from '@axa-ch/react-polymorphic-types';// Default HTML element if the "as" prop is not provided
export const HeadingDefaultElement: ElementType = 'h1';
// List of allowed HTML elements that can be passed via the "as" prop
export type HeadingAllowedElements = typeof HeadingDefaultElement | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
export type HeadingSizes = 1 | 2 | 3 | 4 | 5 | 6;
// Component-specific props
export type HeadingOwnProps = ComponentPropsWithoutRef & {
size?: HeadingSizes;
};
// Extend own props with others inherited from the underlying element type
// Own props take precedence over the inherited ones
export type HeadingProps = PolymorphicProps<
HeadingOwnProps,
T,
HeadingAllowedElements
>;
const HeadingInner = ({
as = HeadingDefaultElement,
size,
className,
children,
...rest
}: HeadingProps) =>
createElement(
as,
{
...rest,
className:
${className} size-${size || 1},
},
children,
);// Memo with generics is tricky
// see also https://fettblog.eu/typescript-react-generic-forward-refs/
export const Heading = memo(HeadingInner) as (
props: HeadingProps,
) => ReturnType;
`The above component can be consumed without any additional overhead as follows:
`tsx
const App = () => (
<>
>
);
`
Exotic Component Example
Polymorphic exotic components allow you to use either DOM nodes or custom rendering functions for your HTML.
`tsx
import { ComponentPropsWithoutRef, createElement, ElementType, ExoticComponent } from 'react';
import { PolymorphicExoticProps, PolymorphicProps } from '@axa-ch/react-polymorphic-types';// Default HTML element if the "as" prop is not provided
export const ContainerDefaultElement: ElementType = 'div';
// List of allowed HTML elements that can be passed via the "as" prop
export type ContainerAllowedDOMElements = typeof ContainerDefaultElement | 'article' | 'section';
export type ContainerAllowedElements = ContainerAllowedDOMElements | ExoticComponent;
// Component-specific props
export type ContainerOwnProps = ComponentPropsWithoutRef;
// Extend own props with others inherited from the underlying element type
// Own props take precedence over the inherited ones
export type ContainerProps = T extends ContainerAllowedDOMElements
? PolymorphicProps, T, ContainerAllowedDOMElements>
: PolymorphicExoticProps, T, ContainerAllowedDOMElements>;
export const Container = ({
as = ContainerDefaultElement,
className,
children,
...rest
}: ContainerProps) =>
createElement(
as,
{
...rest,
className,
},
children,
);
`The above component works with straight HTML nodes or with external exotic components like, for example, the ones provided by framer-motion.
`tsx
import { motion } from 'framer-motion';const App = () => (
<>
{/ Notice that the exotic props here will be automatically inferred /}
as={motion.article}
layout
/>
>
);
`
Exotic Component Example with Ref
Polymorphic exotic components that use refs are slightly more complex and require some additional code to work properly.
`tsx
import { ComponentPropsWithoutRef, createElement, ElementType, ExoticComponent, forwardRef } from 'react';
import { PolymorphicProps, PolymorphicForwardedRef, PolymorphicExoticProps } from '@axa-ch/react-polymorphic-types';// Default HTML element if the "as" prop is not provided
export const ContainerDefaultElement: ElementType = 'div';
// List of allowed HTML elements that can be passed via the "as" prop
export type ContainerAllowedDOMElements = 'div' | 'article' | 'section';
export type ContainerAllowedElements = ContainerAllowedDOMElements | ExoticComponent;
// Component-specific props
export type ContainerOwnProps = ComponentPropsWithoutRef;
// Extend own props with others inherited from the underlying element type
// Own props take precedence over the inherited ones
export type ContainerProps = T extends ContainerAllowedDOMElements
? PolymorphicProps, T, ContainerAllowedDOMElements>
: PolymorphicExoticProps, T, ContainerAllowedDOMElements>;
// Forwarded ref component
const ContainerInner = (
{ as = ContainerDefaultElement, className, children, ...rest }: ContainerProps,
ref: PolymorphicForwardedRef,
) =>
createElement(
as,
{
...rest,
ref,
className,
},
children,
);
// Forward refs with generics is tricky
// see also https://fettblog.eu/typescript-react-generic-forward-refs/
export const Container = forwardRef(ContainerInner) as (
props: ContainerProps & { ref?: PolymorphicForwardedRef },
) => ReturnType;
`With the above example, DOM nodes will be automatically inferred, including when using third-party exotic rendering functions.
`tsx
import { motion } from 'framer-motion';const App = () => {
const div = useRef(null);
// Article and other HTML5 tags are just of type HTMLElement
const article = useRef(null);
return (
<>
ref={div}
as='div'
/>
ref={article}
as={motion.article}
layout
/>
>
);
};
`
Complex Exotic/Functional Component Example
This example combines multiple rendering strategies for your component to allow maximum flexibility for its consumers.
`tsx
// We need to infer the functional component properties so 'any' is used in this case
// You can also add strict types for your functional components, but it will reduce flexibility
import { ComponentPropsWithoutRef, createElement, ElementType, ExoticComponent, FC } from 'react';
import { PolymorphicFunctionalProps, PolymorphicExoticProps, PolymorphicProps } from '@axa-ch/react-polymorphic-types';// Default HTML element if the "as" prop is not provided
export const ContainerDefaultElement: ElementType = 'div';
// List of allowed HTML elements that can be passed via the "as" prop
export type ContainerAllowedDOMElements = 'div' | 'article' | 'section';
export type ContainerAllowedElements = ContainerAllowedDOMElements | ExoticComponent | FC;
// Component-specific props
export type ContainerOwnProps = ComponentPropsWithoutRef;
// Extend own props with others inherited from the underlying element type
// Own props take precedence over the inherited ones
export type ContainerProps = T extends ContainerAllowedDOMElements
? PolymorphicProps, T, ContainerAllowedDOMElements>
: T extends FC
? PolymorphicFunctionalProps, T, ContainerAllowedDOMElements>
: PolymorphicExoticProps, T, ContainerAllowedDOMElements>;
export const Container = ({
as = ContainerDefaultElement,
className,
children,
...rest
}: ContainerProps) =>
createElement(
as,
{
...rest,
className,
},
children,
);
`Let's see how we can use the above component with all its possible rendering options:
`tsx
import { motion } from 'framer-motion';type FooProps = ComponentPropsWithoutRef<'div'> & { size: 'small' | 'large'; name: string };
const Foo: FC = ({ className, size = 'large', ...rest }) => (
{...rest}
className={
${className} the-foo ${size}}
/>
);const App = () => (
<>
size='small'
name='foo'
as={Foo}
/>
as={motion.div}
layout
animate
/>
>
);
``This project wouldn't exist without react-polymorphic-types
[ci-image]: https://img.shields.io/github/actions/workflow/status/axa-ch/react-polymorphic-types/ci.yml?style=flat-square&branch=main
[ci-url]: https://github.com/axa-ch/react-polymorphic-types/actions
[license-image]: http://img.shields.io/badge/license-MIT-000000.svg?style=flat-square
[license-url]: LICENSE
[npm-version-image]: https://img.shields.io/npm/v/@axa-ch/react-polymorphic-types.svg?style=flat-square
[npm-downloads-image]: https://img.shields.io/npm/dm/@axa-ch/react-polymorphic-types.svg?style=flat-square
[npm-url]: https://npmjs.org/package/@axa-ch/react-polymorphic-types