Polymorphic components: the as prop versus asChild and Slot

One behavior, many elements

The need is universal in design systems: Button must sometimes be a button, sometimes an a, sometimes a router Link — same padding, same focus ring, same press states. The naive answers are all wrong. Nesting (a around button) is invalid HTML with broken semantics — interactive inside interactive confuses every assistive technology. Copying the styles onto a second component drifts within a quarter. Slapping onClick plus styles on a div loses keyboard activation, focus, and the accessibility tree entirely. So the real options are two: change what the component renders (the as prop) or adopt the element the caller already wrote (asChild).

The as prop, and the bill TypeScript sends

At runtime, as is almost nothing:

function Box({ as, ...props }) {
  const Comp = as ?? "div";
  return <Comp {...props} />;
}
// <Box as="a" href="/docs">Docs</Box>  →  renders <a href="/docs">

The entire cost lives in the types. A correct polymorphic component must say: “my props are my own props, plus the props of whatever element as names, minus collisions — and my ref is typed for that element.” That last clause is the notorious one: the ref type must be derived per call site (ComponentPropsWithRef<E>["ref"]), and the props type is a conditional/mapped type over E extends ElementType. It works, and every utility library that offers it carries pages of caveats — because the instantiation cost scales with call sites. Each <Box as={...}> makes the compiler resolve the conditional type against the full element map; at thousands of call sites that is measurable tsc time and visible editor latency, and error messages stop naming your code and start naming type machinery. There is also a semantic trap the types cannot catch: your component’s behavioral props may be meaningless on the new element — disabled on an anchor does nothing natively, so the component must translate it (aria-disabled, blocked handlers) or honestly not support it. The honest verdict: as is the right tool for style-system primitives — Box, Text, Stack — where own-props are few, behavior is nil, and the polymorphism is purely about which tag carries the styles.

asChild and Slot: composition instead of type gymnastics

Radix popularized the alternative. With asChild, the component renders no element of its own — it renders a Slot, and Slot clones its single child, merging the component’s props into it:

<Button asChild>
  <Link to="/billing">Upgrade</Link>
</Button>
// Renders ONE element: the Link's <a>, now carrying Button's
// className, data attributes, event handlers, and ref.

Inside, Button does const Comp = asChild ? Slot : "button". Slot takes the child element and produces a clone with merged props — the mechanics matter because you will debug them:

• className: concatenated — both the slot’s and the child’s classes survive.
• style: object-merged, the child’s properties winning on collision.
• event handlers: chained, child first — the child’s onClick runs, then the slot’s. Well-built primitives compose with a defaultPrevented check, so a child that calls event.preventDefault() can stop the primitive’s own logic; a naive merge runs both unconditionally, which is how double-firing bugs ship.
• ref: composed — a callback ref that fills both the parent’s and the child’s. React 19 made this materially simpler: ref is now a regular prop on function components, so merging no longer needs forwardRef wrappers or reaching into element.ref (deprecated access that warned through React 18).

The contract this buys: no type gymnastics — Button keeps its own simple props, and the child keeps its own; TypeScript checks each side separately. The price is two new failure modes. Multiple children throw: Slot must clone exactly one element (React.Children.only), so <Button asChild><Icon /><span>Save</span></Button> is a runtime error — wrap them in one element. And the child must cooperate: Slot merges props into the child element, but if the child is a custom component that ignores unknown props — renders its own span without spreading — every merged handler, ARIA attribute, and ref silently vanishes. The rendered widget looks right and does nothing; the debugging move is inspecting the DOM for the expected data-state/aria-* attributes.

Choosing: as for primitives, asChild for behavior

The two tools partition cleanly along what the component is:

• as for style-system primitives. Box, Text, Stack, Grid: no behavior, few own props, shallow inference. The polymorphism is “which tag carries these styles” — as="section", as="label". Keep the accepted union narrow (intrinsic elements, maybe a couple of components) and the TypeScript bill stays small.
• asChild for behavior wrappers. Button, Tooltip.Trigger, Dialog.Trigger, DropdownMenu.Trigger: rich behavior (handlers, ARIA, focus), and the caller’s element is often itself a component (router Link) with its own props. asChild sidesteps the type explosion entirely and composes behaviors — Tooltip.Trigger asChild around Dialog.Trigger asChild around your Button stacks three behavior sets onto one rendered element, something as cannot express at all.

The remaining discipline is documentation: an asChild API must state its child contract loudly — one element child; the child must spread unknown props and accept a ref. Design systems that skip this paragraph generate a steady stream of “tooltip silently does not open” tickets from teams whose child component swallowed the merge.