> _Everything should be made as simple as possible, but not simpler._ —Albert > Einstein As a design system engineer, my primary goal is to deliver a consistent user experience across a large number of products. Succeeding in this requires consistent reuse of the components I build. Consistent reuse of these components requires them to adapt to a wide range of use cases. Otherwise, my clients will opt out and roll their own components, typically losing important functionality or design details in the process. My most essential technical tool for delivering the required flexibility is the notion of the _polymorphic component_. Before jumping into code, allow me to explain this important concept and why it's so useful. ## What are polymorphic components? A polymorphic component delivers consistent visual design and functionality in a context-sensitive manner as follows: 1. It offers direct control over the rendered markup, allowing developers to [improve accessibility via semantic HTML](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/HTML). 1. Its appearance and/or behavior can be combined with those of another component. A `Button` component is the canonical example of component polymorphism: By default, it just renders a HTML ` ``` For TypeScript users, the `as` prop can be especially interesting because a typical type definition will guard against invalid prop combinations depending on the value of the `as` prop. For example, this would not compile since `href` is not a valid HTML ` ``` A couple of years ago, the `as` prop was practically synonymous with the term _polymorphic component_, and for good reason. It is widely recognized; it's easy to use; and it offers a reasonable degree of type safety, which unfortunately is not true of its "successor" (more on that later). But, to be fair, it's not a perfect solution. #### Problems with the `as` prop Over the last two years, the `as` prop has been challenged as the de-facto standard for polymorphic components on the following points: 1. Slow TypeScript performance 1. Poor type inference 1. Prop collisions To be honest, I haven't experienced the first two issues myself; but I _can_ relate to the third issue, and it is significant. ##### Prop collisions Consider two polymorphic components: `Highlight`, which contributes a configurable background color to an element, and `Outline`, which similarly adds a colored outline around an element. ![Highlight and Outline component examples](assets/images/highlight-outline/highlight-outline.png) ```tsx <> Highlight Outline ``` You can combine the two using the `as` prop. ![Highlight and Outline combination](assets/images/highlight-outline/combo-monochrome.png) ```tsx Highlight + Outline ``` But what if you want a two-tone effect? ![Two-tone effect using the Highlight and Outline components](assets/images/highlight-outline/combo-two-tone.png) ```tsx Highlight + Outline ``` Unfortunately, it isn't possible to achieve this on the basis of the `Highlight` and `Outline` components because you can't control each component's `color` prop independently. The duplicate `color` prop in the code example simply wouldn't compile. Now let's return for a moment to the monochromatic combination that actually works. ![Highlight and Outline combination](assets/images/highlight-outline/combo-monochrome.png) By default, this renders a generic `

` element. But what if you need to render a ` ``` To the compiler, this just looks like a plain HTML `` element nested as the child of some ` ``` The resulting HTML would look essentially like the following—with no TypeScript error to alert you that the `disabled` prop [is not compatible](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes) with an `` element. ```html Get started ``` On the other hand, each of the following _would_ result in a type error as expected. ```tsx <> Get started ``` To compare for yourself, have a look at [this demo](https://githubbox.com/nsaunders/writing/tree/master/posts/function-aschild-intro/sandboxes/aschild-prop-invalid-html). ##### No control over prop forwarding `asChild` assumes a straightforward 1-to-1 mapping between the props forwarded from the "parent" and the props accepted by the "child". But, as the previous example shows, that may be a bit too optimistic. A reasonable implementation for a "disabled" `` element might look something like this: ```tsx { e.preventDefault(); }}> Get started ``` In the button-as-link context, the `disabled` prop forwarded from the `Button` "parent" would be reflected in three distinct "child" props: `className`, `aria-disabled`, and `onClick`. Because `asChild` hides its prop forwarding logic, it isn't possible to achieve this—instead, you'll be stuck with that invalid `disabled` attribute in the resulting HTML, as discussed earlier. ##### Contraindicated use of `cloneElement` The implementation of the `asChild` prop (Radix's [`Slot` component](https://github.com/radix-ui/primitives/blob/eca6babd188df465f64f23f3584738b85dba610e/packages/react/slot/src/Slot.tsx#L64-L67)), utilizes the `cloneElement` function. However, the [React documentation](https://react.dev/reference/react/cloneElement) warns that "using `cloneElement` is uncommon and can lead to fragile code" while "[making] it hard to tell how the data flows through your app". It continues on to [recommend the render prop as a "more explicit" alternative](https://react.dev/reference/react/cloneElement#alternatives) where "you can clearly trace" the props. #### Final thoughts on the `asChild` prop Over the years, I've used many technologies that initially appeared to make things easier but eventually taught me that they were merely hiding complexity, rather than eliminating it. Unfortunately, the `asChild` prop seems to fit that profile. It solves the problems of the `as` prop by pretending that one element is actually two. The type checker has no knowledge of `asChild`'s implicit magic and is powerless to prevent the "parent" component from injecting any number of props into the "child" element, whether compatible or not. The side effects of this design might include tight coupling between "parent" and "child" components, whose implementation details must line up without compiler help; invalid HTML; and incomplete functionality, particularly in the case of a "child" component whose code you don't control (e.g. a third-party `Link` component). Moreover, the React docs warn that `asChild`'s use of `cloneElement` "makes it harder to trace the data flow". To its credit, the `asChild` prop has raised awareness about some issues with the `as` prop, and it _has_, technically, solved those issues. It has also reminded us that the `as` prop isn't the only way to do polymorphic components. ## Introducing _Function asChild_ After realizing the many pitfalls of the `as` and `asChild` props, I began the search for a safer and more flexible approach to polymorphic components. I'm happy to report that, rather than inventing something new, I discovered an approach that builds upon an established React pattern dating back to at least 2016, a [render prop](https://www.patterns.dev/posts/render-props-pattern) variant known as [Function as Child Component](https://www.merrickchristensen.com/articles/function-as-child-components/). ### A quick preview Before we dive into the implementation, I'd like to offer a glimpse of what _Function asChild_ looks like from a "client code" perspective. Let's return to the polymorphic `Button` once again. By default, the `Button` component provides the same interface as the HTML `button` tag, enhanced with any additional props, e.g. a `variant`. ```tsx ``` When you want to render a different type of element, you pass a render function as child. ```tsx ``` If you squint a little bit, you might recognize that this JSX structure actually resembles its `asChild` "equivalent". However, since the child is a render function rather than an element, this solution avoids implicit magic, doesn't break the type checker, and produces valid HTML. If you've seen render props before, you might have a pretty good idea of what's going on here. But it's easy to miss some essential details of this approach without walking through its implementation and usage. So, with that, let's get started. ### Polymorphic component implementation The first step is to define the interface between the `Button` component and the render function. I usually refer to this as the _forward props_. For a simple component whose scope is limited to visual styling, often this will consist of a single `style` or `className` prop. ```tsx export type ButtonForwardProps = { className?: string; }; ``` Next, let's define the `Button` props. The union type forces the client code to choose between the default HTML `button` tag interface and the Function asChild interface. The `variant` prop is available in either case. ```tsx import { ComponentProps, ReactElement } from "react"; import { U } from "ts-toolbelt"; export type ButtonProps = U.Strict< ( | ComponentProps<"button"> | { children: (forwardProps: ForwardProps) => ReactElement } ) & { variant?: "primary" | "secondary"; } >; ``` After defining the prop types, the next step is to set up the `Button` as a [ref-forwarding](https://react.dev/reference/react/forwardRef) function component. The ref forwarding is useful for the default case of a HTML ` ); }, ) as ComponentType; ``` That's all it takes to implement the polymorphic `Button` component! Due to a quirk of TypeScript, however, how you _use_ the component can make a significant difference in terms of type safety. So, to learn how to use it in the most effective way, read on. ### Polymorphic component usage At this point, we actually have a working polymorphic component. And here is how most people (myself included) would be inclined to use it: ```tsx ``` Unfortunately, TypeScript doesn't work as expected sometimes, and the prop spread is one such case. Due to a long-standing [issue](https://github.com/Microsoft/TypeScript/issues/29883), excess props don't produce a compiler error. You won't love the workaround, but hopefully you'll appreciate its effectiveness in preventing prop forwarding mistakes. #### Avoiding the spread When in doubt, the best way to cope with the prop spread's unsound nature is to avoid it entirely. That means fully destructuring the props and forwarding them individually. ```tsx ``` But even this has its pitfalls: 1. **Forgotten props**: It's easy to forget to destructure some of the props. Even if you account for all of them initially, additional props could be added to the `ButtonForwardProps` interface in the future. 2. **Unused props**: Similarly, it's easy to forget to actually forward some of the props, even if you remembered to destructure them. Fortunately, each of these problems has a solution. #### Exhaustiveness check Let's make a a small change by adding `...restProps` to the prop-destructuring expression. ```tsx ``` If you've destructured all of the props as intended, `restProps` will be an empty object, i.e. `{}`. You can assert this with the `exhausted` function, which produces a TypeScript error when called with a non-empty object. ```tsx // Keep this somewhere like a `util.ts` module. function exhausted(x: Record) { return true as const; } ``` For example, here's what happens if you forget about the `className` prop: ![A TypeScript error surfaced when the props are not fully destructured](assets/images/editor-help/not-exhausted.png) As I mentioned earlier, it's still possible to destructure a prop and forget to forward it. Next, I'll show you an additional measure to prevent this common mistake. #### Unused prop check In general, all of the props passed to a render function should actually be used in some way; otherwise, aspects of the component's appearance or behavior might be lost. Since the `exhausted` function already guarantees that the props object is fully destructured, all that's left is to ensure that none of these props are unused. For this, I simply recommend the ESLint rule [`@typescript-eslint/no-unused-vars`](https://typescript-eslint.io/rules/no-unused-vars/). With this rule enabled, here's what happens if you forget to forward the `className` prop: ![An ESLint error showing that one of the props is unused](assets/images/editor-help/unused-prop.png) If you aren't already using ESLint, see [typescript-eslint's Getting Started guide](https://typescript-eslint.io/getting-started) for more information on how to configure your project. ### Interactive demos I invite you to experience Function asChild through a couple of code demos I've prepared: - [Polymorphic `Button`](https://githubbox.com/nsaunders/writing/tree/master/posts/function-aschild-intro/sandboxes/function-aschild-button) - [Multiple-component composition](https://githubbox.com/nsaunders/writing/tree/master/posts/function-aschild-intro/sandboxes/function-aschild-composition) ### Reviewing the solution Now that you've seen how to implement and use the Function asChild approach for polymorphic components, let's consider its relative advantages: 1. Predictable TypeScript performance and type inference 1. Prop collision avoidance 1. High degree of type safety 1. Transparent prop forwarding scheme that you control 1. Valid HTML output 1. Ability to compose three or more components 1. Loose coupling between components Compared to the `as` and `asChild` props, Function asChild offers a more flexible and far safer approach to polymorphic components. ## Wrapping up Polymorphic components are extremely useful and, unfortunately, more complicated than I once realized. The `as` and `asChild` props, each in their own way, try to make polymorphic components simpler than they actually are, and this is where their problems begin. On the other hand, Function asChild hides nothing from you. It prioritizes thoroughness and precision; while hopefully becoming more convenient in the future as the TypeScript team improves type checking for prop spreads. For now, selecting the right approach comes down to "convenience" versus _correctness_. If you've made it this far, I know you'll choose wisely.

Latest post

From CSS madness to CSS Hooks

Worth a read

Function asChild