Behind the ‘as’ prop: polymorphism done well

A button renderable as a link has quirky types in React. How could custom tags be assigned to such components?

Reusable bits of a site mostly have rigid HTML semantics. Some of those constraints are unwarranted, though.

Starting with a simple button, we may end up using it for navigation:

import { clsx } from "clsx/lite"; // Joins CSS class names


interface MyButtonProps
	extends React.ComponentPropsWithoutRef<"button"> {
	className?: string; // Redundant but kept for explicitness
}


function MyButton({ className, ...props }: MyButtonProps) {
	return (
		<button
			className={clsx(className, "my-button")}
			{...props}
		/>
	);
}


function App() {
	return (
		<MyButton onClick={() => navigation.navigate("/")}>
			Home
		</MyButton>
	);
}

Despite acting okay, this pattern has major flaws. Above all, we broke the first rule of ARIA:

If you can use a native HTML element or attribute with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so.

Abiding that, a link will suffice our needs:

<a href="/" className="my-button">
	Home
</a>

Styling may be borrowed from within MyButton, just as embraced by Class Variance Authority. However…

CSS has its limits #

Many accessible states can only be exposed via HTML. For instance, a toggle button should utilize the aria-pressed attribute, unless its label changes when clicked.

No wonder component-oriented separation of concerns feels so natural.

Encapsulation of behavior #

Our goal is to make MyButton render an <a> element when desired, falling back to <button> in the absence of an as prop.

In JSX, lowercase tags like <a> refer to built-in HTML/SVG elements. Conversely, components have their first letter capitalized:

<MyButton onClick={() => navigation.reload()}>Reload</MyButton>

This gets transpiled into a function call behind the scenes:

import { jsx } from "react/jsx-runtime";


jsx(
	MyButton, // type
	{ onClick: () => navigation.reload() }, // props
	"Reload", // children (optional)
);

We may pass variables along to that, e.g. for the type:

let as = MyButton;
jsx(as, {}); // Renders `<button>` ✅

Yet we can’t follow suit in JSX because as is lowercase, implying a built-in element:

let as = MyButton;
<as />; // Renders `<as>` ❌ — via `jsx("as", {})`

How might we tell JSX otherwise? Just use a PascalCase variable:

let as = MyButton;
const Element = as;
<Element />; // Renders `<button>` ✅

That idea forms the basis for our polymorphic component:

import { clsx } from "clsx/lite";


function MyButton({ as = "button", className, ...props }) {
	const Element = as;
	return (
		<Element
			className={clsx(className, "my-button")}
			{...props}
		/>
	);
}

So far so good. The biggest hurdle is yet to come, though.

Adding types #

Let’s begin from the inside out:

import { clsx } from "clsx/lite";


function MyButton({ as = "button", className, ...props }) {
	const Element: React.ElementType = as;
	return (
		<Element
			className={clsx(className, "my-button")}
			{...props}
		/>
	);
}

It’s tempting to use React.ElementType<P = any> as is. However, that goes over all the built-in elements, keeping the ones taking P as attributes.

Luckily, we can narrow the set of tags endorsed, reducing type instantiations by an order of magnitude:

type MyButtonElementType = React.ElementType<
	any,
	"button" | "a" // Other tags could be wrapped by components
>;

(A tag-independent abstraction should likely be refactored into a hook at this point.)

At last, it’s time to declare the props of MyButton:

• With discriminated unions in mind, we merge the as prop using a distributive conditional type since Omit<T, K> only retains properties common to every object in the T union.
• Components rendered by MyButton may not require an as prop because that can’t be passed along from outside. P & { as?: never } guards against such P types.

import { clsx } from "clsx/lite";


type Merge<T, U> = DistributiveOmit<T, keyof U> & U;
type DistributiveOmit<
	T,
	K extends PropertyKey,
> = T extends unknown ? Omit<T, K> : never;


type MyButtonElementType = React.ElementType<
	any,
	"button" | "a"
>;


type MyButtonProps<T extends MyButtonElementType = "button"> =
	Merge<
		React.ComponentPropsWithoutRef<T> & { as?: never },
		{
			as?: T;
			className?: string;
		}
	>;


function MyButton<T extends MyButtonElementType = "button">({
	as = "button" as T,
	className,
	...props
}: MyButtonProps<T>) {
	const Element: MyButtonElementType = as;
	return (
		<Element
			className={clsx(className, "my-button")}
			{...props}
		/>
	);
}

This concludes our journey towards creating a type-safe polymorphic component in React.

While type assertions are bad practice in TypeScript, we may either:

• Make the as prop required, undermining convenience.
• Define const Element = as ?? "button" and remove the assignment from as = "button". This results in bogus auto-completion for Element props.
• Assume the default value "button" is assignable to T, even though setting the type argument explicitly like <MyButton<"a">> voids that.

I’ve opted for the latter but ultimately, it’s a matter of personal choice. Life is never black and white, hence being full of beauty 🌈