This example showcases a simple polymorphic heading element. It allows you to independently define its size and markup using props.

1import { ComponentPropsWithoutRef, createElement, ElementType } from 'react';
2import { PolymorphicProps } from '@axa-ch/react-polymorphic-types';
3
4// Default HTML element if the "as" prop is not provided
5export const HeadingDefaultElement: ElementType = 'h1';
6// List of allowed HTML elements that can be passed via the "as" prop
7export type HeadingAllowedElements = typeof HeadingDefaultElement | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
8export type HeadingSizes = 1 | 2 | 3 | 4 | 5 | 6;
9
10// Component-specific props
11export type HeadingOwnProps<T extends HeadingAllowedElements> = ComponentPropsWithoutRef<T> & {
12  size?: HeadingSizes;
13};
14
15// Extend own props with others inherited from the underlying element type
16// Own props take precedence over the inherited ones
17export type HeadingProps<T extends HeadingAllowedElements = typeof HeadingDefaultElement> = PolymorphicProps<
18  HeadingOwnProps<T>,
19  T,
20  HeadingAllowedElements
21>;
22
23export const Heading = <T extends HeadingAllowedElements>({
24  as = HeadingDefaultElement,
25  size,
26  className,
27  children,
28  ...rest
29}: HeadingProps<T>) =>
30  createElement(
31    as,
32    {
33      ...rest,
34      className: `${className} size-${size || 1}`,
35    },
36    children,
37  );

You can use the Heading component in your application as shown below:

1const App = () => (
2  <article>
3    <Heading
4      as='h1'
5      size={2}
6    >
7      My Main Headline
8    </Heading>
9    <Heading
10      as='h2'
11      size={5}
12    >
13      A Subtitle
14    </Heading>
15
16    {/* The following component will throw a TypeScript error because 'div' elements are not allowed here */}
17    <Heading
18      as='div'
19      size={5}
20    >
21      A Subtitle
22    </Heading>
23    <p>A description</p>
24  </article>
25);

This example is similar to the previous one, but it also allows the use of React refs.

1import { ComponentPropsWithoutRef, createElement, ElementType, forwardRef } from 'react';
2import { PolymorphicProps, PolymorphicForwardedRef } from '@axa-ch/react-polymorphic-types';
3
4// Default HTML element if the "as" prop is not provided
5export const HeadingDefaultElement: ElementType = 'h1';
6// List of allowed HTML elements that can be passed via the "as" prop
7export type HeadingAllowedElements = typeof HeadingDefaultElement | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
8export type HeadingSizes = 1 | 2 | 3 | 4 | 5 | 6;
9
10// Component-specific props
11export type HeadingOwnProps<T extends HeadingAllowedElements> = ComponentPropsWithoutRef<T> & {
12  size?: HeadingSizes;
13};
14
15// Extend own props with others inherited from the underlying element type
16// Own props take precedence over the inherited ones
17export type HeadingProps<T extends HeadingAllowedElements> = PolymorphicProps<
18  HeadingOwnProps<T>,
19  T,
20  HeadingAllowedElements
21>;
22
23const HeadingInner = <T extends HeadingAllowedElements>(
24  {
25    as = HeadingDefaultElement,
26    size,
27    className,
28    children,
29    ...rest
30  }: PolymorphicProps<HeadingOwnProps<T>, T, HeadingAllowedElements>,
31  // notice the use of the PolymorphicForwardedRef type here
32  ref: PolymorphicForwardedRef<T>,
33) =>
34  createElement(
35    element,
36    {
37      ...rest,
38      ref,
39      className: `${className} size-${size || 1}`,
40    },
41    children,
42  );
43
44// Forward refs with generics is tricky
45// see also https://fettblog.eu/typescript-react-generic-forward-refs/
46export const Heading = forwardRef<HeadingAllowedElements>(HeadingInner) as unknown as <
47  T extends HeadingAllowedElements,
48>(
49  props: HeadingProps<T> & { ref?: PolymorphicForwardedRef<T> },
50) => ReturnType<typeof HeadingInner>;

Using the @axa-ch/react-polymorphic-types types will allow you to automatically infer the proper ref DOM node.

1const App = () => {
2  // The use of HTMLHeadingElement type is safe
3  const ref = useRef<HTMLHeadingElement | null>(null);
4
5  return (
6    <Heading
7      ref={ref}
8      as='h2'
9    />
10  );
11};

This example is similar to the previous one, but with React 19 the refs forwarding got much easier

1import { ComponentPropsWithoutRef, createElement, ElementType, forwardRef } from 'react';
2import { PolymorphicProps, PolymorphicForwardedRef } from '@axa-ch/react-polymorphic-types';
3
4// Default HTML element if the "as" prop is not provided
5export const HeadingDefaultElement: ElementType = 'h1';
6// List of allowed HTML elements that can be passed via the "as" prop
7export type HeadingAllowedElements = typeof HeadingDefaultElement | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
8export type HeadingSizes = 1 | 2 | 3 | 4 | 5 | 6;
9
10// Component-specific props
11export type HeadingOwnProps<T extends HeadingAllowedElements> = ComponentPropsWithoutRef<T> & {
12  size?: HeadingSizes;
13  ref?: PolymorphicForwardedRef<T>;
14};
15
16// Extend own props with others inherited from the underlying element type
17// Own props take precedence over the inherited ones
18export type HeadingProps<T extends HeadingAllowedElements> = PolymorphicProps<
19  HeadingOwnProps<T>,
20  T,
21  HeadingAllowedElements
22>;
23
24const Heading = <T extends HeadingAllowedElements>({
25  as = HeadingDefaultElement,
26  size,
27  className,
28  ref,
29  children,
30  ...rest
31}: PolymorphicProps<HeadingOwnProps<T>, T, HeadingAllowedElements>) =>
32  createElement(
33    element,
34    {
35      ...rest,
36      ref,
37      className: `${className} size-${size || 1}`,
38    },
39    children,
40  );

Using the @axa-ch/react-polymorphic-types types will allow you to automatically infer the proper ref DOM node.

1const App = () => {
2  // The use of HTMLHeadingElement type is safe
3  const ref = useRef<HTMLHeadingElement | null>(null);
4
5  return (
6    <Heading
7      ref={ref}
8      as='h2'
9    />
10  );
11};

This example shows the use of React.memo with a polymorphic component.

1import { ComponentPropsWithoutRef, createElement, ElementType, memo } from 'react';
2import { PolymorphicProps } from '@axa-ch/react-polymorphic-types';
3
4// Default HTML element if the "as" prop is not provided
5export const HeadingDefaultElement: ElementType = 'h1';
6// List of allowed HTML elements that can be passed via the "as" prop
7export type HeadingAllowedElements = typeof HeadingDefaultElement | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
8export type HeadingSizes = 1 | 2 | 3 | 4 | 5 | 6;
9
10// Component-specific props
11export type HeadingOwnProps<T extends HeadingAllowedElements> = ComponentPropsWithoutRef<T> & {
12  size?: HeadingSizes;
13};
14
15// Extend own props with others inherited from the underlying element type
16// Own props take precedence over the inherited ones
17export type HeadingProps<T extends HeadingAllowedElements> = PolymorphicProps<
18  HeadingOwnProps<T>,
19  T,
20  HeadingAllowedElements
21>;
22
23const HeadingInner = <T extends HeadingAllowedElements>({
24  as = HeadingDefaultElement,
25  size,
26  className,
27  children,
28  ...rest
29}: PolymorphicProps<HeadingOwnProps<T>, T, HeadingAllowedElements>) =>
30  createElement(
31    element,
32    {
33      ...rest,
34      className: `${className} size-${size || 1}`,
35    },
36    children,
37  );
38
39// Memo with generics is tricky
40// see also https://fettblog.eu/typescript-react-generic-forward-refs/
41export const Heading = memo(HeadingInner) as <T extends HeadingAllowedElements>(
42  props: HeadingProps<T>,
43) => ReturnType<typeof HeadingInner>;

The above component can be consumed without any additional overhead as follows:

1const App = () => (
2  <>
3    <Heading as='h2' />
4  </>
5);

Polymorphic exotic components allow you to use either DOM nodes or custom rendering functions for your HTML.

1import { ComponentPropsWithoutRef, createElement, ElementType, ExoticComponent } from 'react';
2import { PolymorphicExoticProps, PolymorphicProps } from '@axa-ch/react-polymorphic-types';
3
4// Default HTML element if the "as" prop is not provided
5export const ContainerDefaultElement: ElementType = 'div';
6// List of allowed HTML elements that can be passed via the "as" prop
7export type ContainerAllowedDOMElements = typeof ContainerDefaultElement | 'article' | 'section';
8export type ContainerAllowedElements = ContainerAllowedDOMElements | ExoticComponent;
9
10// Component-specific props
11export type ContainerOwnProps<T extends ContainerAllowedDOMElements> = ComponentPropsWithoutRef<T>;
12
13// Extend own props with others inherited from the underlying element type
14// Own props take precedence over the inherited ones
15export type ContainerProps<T extends ContainerAllowedElements> = T extends ContainerAllowedDOMElements
16  ? PolymorphicProps<ContainerOwnProps<T>, T, ContainerAllowedDOMElements>
17  : PolymorphicExoticProps<ContainerOwnProps<ContainerAllowedDOMElements>, T, ContainerAllowedDOMElements>;
18
19export const Container = <T extends ContainerAllowedElements>({
20  as = ContainerDefaultElement,
21  className,
22  children,
23  ...rest
24}: ContainerProps<T>) =>
25  createElement(
26    element,
27    {
28      ...rest,
29      className,
30    },
31    children,
32  );

The above component works with straight HTML nodes or with external exotic components like, for example, the ones provided by framer-motion.

1import { motion } from 'framer-motion';
2
3const App = () => (
4  <>
5    <Container as='div' />
6    {/* Notice that the exotic props here will be automatically inferred */}
7    <Container
8      as={motion.article}
9      layout
10    />
11  </>
12);

Polymorphic exotic components that use refs are slightly more complex and require some additional code to work properly.

1import { ComponentPropsWithoutRef, createElement, ElementType, ExoticComponent, forwardRef } from 'react';
2import { PolymorphicProps, PolymorphicForwardedRef, PolymorphicExoticProps } from '@axa-ch/react-polymorphic-types';
3
4// Default HTML element if the "as" prop is not provided
5export const ContainerDefaultElement: ElementType = 'div';
6// List of allowed HTML elements that can be passed via the "as" prop
7export type ContainerAllowedDOMElements = 'div' | 'article' | 'section';
8export type ContainerAllowedElements = ContainerAllowedDOMElements | ExoticComponent;
9
10// Component-specific props
11export type ContainerOwnProps<T extends ContainerAllowedDOMElements> = ComponentPropsWithoutRef<T>;
12
13// Extend own props with others inherited from the underlying element type
14// Own props take precedence over the inherited ones
15export type ContainerProps<T extends ContainerAllowedElements> = T extends ContainerAllowedDOMElements
16  ? PolymorphicProps<ContainerOwnProps<T>, T, ContainerAllowedDOMElements>
17  : PolymorphicExoticProps<ContainerOwnProps<ContainerAllowedDOMElements>, T, ContainerAllowedDOMElements>;
18
19// Forwarded ref component
20const ContainerInner = <T extends ContainerAllowedElements>(
21  { as = ContainerDefaultElement, className, children, ...rest }: ContainerProps<T>,
22  ref: PolymorphicForwardedRef<T>,
23) =>
24  createElement(
25    element,
26    {
27      ...rest,
28      ref,
29      className,
30    },
31    children,
32  );
33
34// Forward refs with generics is tricky
35// see also https://fettblog.eu/typescript-react-generic-forward-refs/
36export const Container = forwardRef<ContainerAllowedElements>(ContainerInner) as <T extends ContainerAllowedElements>(
37  props: ContainerProps<T> & { ref?: PolymorphicForwardedRef<T> },
38) => ReturnType<typeof ContainerInner>;

With the above example, DOM nodes will be automatically inferred, including when using third-party exotic rendering functions.

1import { motion } from 'framer-motion';
2
3const App = () => {
4  const div = useRef<HTMLDivElement | null>(null);
5  // Article and other HTML5 tags are just of type HTMLElement
6  const article = useRef<HTMLElement | null>(null);
7
8  return (
9    <>
10      <Container
11        ref={div}
12        as='div'
13      />
14      <Container
15        ref={article}
16        as={motion.article}
17        layout
18      />
19    </>
20  );
21};

This example combines multiple rendering strategies for your component to allow maximum flexibility for its consumers.

1// We need to infer the functional component properties so 'any' is used in this case
2// You can also add strict types for your functional components, but it will reduce flexibility
3import { ComponentPropsWithoutRef, createElement, ElementType, ExoticComponent, FC } from 'react';
4import { PolymorphicFunctionalProps, PolymorphicExoticProps, PolymorphicProps } from '@axa-ch/react-polymorphic-types';
5
6// Default HTML element if the "as" prop is not provided
7export const ContainerDefaultElement: ElementType = 'div';
8// List of allowed HTML elements that can be passed via the "as" prop
9export type ContainerAllowedDOMElements = 'div' | 'article' | 'section';
10export type ContainerAllowedElements = ContainerAllowedDOMElements | ExoticComponent | FC<any>;
11
12// Component-specific props
13export type ContainerOwnProps<T extends ContainerAllowedDOMElements> = ComponentPropsWithoutRef<T>;
14
15// Extend own props with others inherited from the underlying element type
16// Own props take precedence over the inherited ones
17export type ContainerProps<T extends ContainerAllowedElements> = T extends ContainerAllowedDOMElements
18  ? PolymorphicProps<ContainerOwnProps<T>, T, ContainerAllowedDOMElements>
19  : T extends FC<any>
20    ? PolymorphicFunctionalProps<ContainerOwnProps<ContainerAllowedDOMElements>, T, ContainerAllowedDOMElements>
21    : PolymorphicExoticProps<ContainerOwnProps<ContainerAllowedDOMElements>, T, ContainerAllowedDOMElements>;
22
23export const Container = <T extends ContainerAllowedElements>({
24  as = ContainerDefaultElement,
25  className,
26  children,
27  ...rest
28}: ContainerProps<T>) =>
29  createElement(
30    as,
31    {
32      ...rest,
33      className,
34    },
35    children,
36  );

Let's see how we can use the above component with all its possible rendering options:

1import { motion } from 'framer-motion';
2
3type FooProps = ComponentPropsWithoutRef<'div'> & { size: 'small' | 'large'; name: string };
4
5const Foo: FC<FooProps> = ({ className, size = 'large', ...rest }) => (
6  <div
7    {...rest}
8    className={`${className} the-foo ${size}`}
9  />
10);
11
12const App = () => (
13  <>
14    <Container as='div' />
15    <Container
16      size='small'
17      name='foo'
18      as={Foo}
19    />
20    <Container
21      as={motion.div}
22      layout
23      animate
24    />
25  </>
26);