Composable Components

Quick Guide: Design component APIs the way headless primitive libraries do: a component owns behavior, state and accessibility -- the consumer owns markup and styling. Split configuration props into compound parts sharing scoped context, support controlled and uncontrolled use from the same API, let consumers substitute the rendered element (asChild or render), expose every state as a data-* attribute, and compose -- never replace -- the props, refs and handlers you receive. This is an alignment skill: run any existing component through the checklist at the end and fix what fails.

---

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST express variation as parts and children, NOT as configuration props -- a new visual requirement must be satisfiable by rearranging JSX, never by adding a boolean or a renderX prop)

(You MUST ship the full state triple for every piece of component state -- value + defaultValue + onValueChange -- and NEVER copy a controlled prop into internal state)

(You MUST compose props, event handlers and refs that arrive from the consumer, NEVER replace them -- the consumer's handler runs first and must be able to suppress your internal behavior)

(You MUST expose state as data-* attributes on every part and keep behavior parts visually unopinionated -- no default classNames, no inline colors, no baked-in transitions)

(You MUST read the component's current API and all of its call sites before changing it -- alignment is a refactor of a contract, and every consumer is part of that contract)

</critical_requirements>

---

Auto-detection: compound components, component API design, asChild, Slot, render prop, useRender, mergeProps, controlled uncontrolled, defaultValue, onValueChange, data-state, data attributes, headless component, primitive component, forwardRef, prop forwarding, composeRefs, composeEventHandlers, context scoping, roving tabindex, typeahead, focus trap, polymorphic component, children as composition, boolean prop explosion

When to use:

• Designing the public API of a new reusable component
• Aligning an existing component that has accumulated configuration props, booleans or renderX props
• Deciding whether a new requirement becomes a prop, a part, or a slot
• Adding controlled/uncontrolled duality to a component that only supports one mode
• Making a component polymorphic so consumers can swap the rendered element
• Moving styling decisions out of a component and into the consumer's stylesheet
• Wiring accessibility structurally (ids, roles, focus, keyboard) instead of per-consumer
• Reviewing a component library PR for API shape and forwarding discipline

When NOT to use:

• One-off application components rendered in exactly one place with no reuse pressure
• Layout containers that genuinely take no state and no variation
• Deciding which primitive library to adopt -- this skill is about API shape, not tool selection
• Visual design decisions: spacing scales, color systems, variant naming

Key patterns covered:

• Compound components over configuration props
• Controlled/uncontrolled duality and the change-details object
• Polymorphism: asChild + Slot, and the render prop + useRender
• State as data-* attributes; zero visual opinions in behavior parts
• Prop forwarding discipline: rest-spread, ref forwarding, handler composition
• Context scoping and clear out-of-Root errors
• Structural accessibility: id wiring, focus management, roving tabindex, typeahead
• Children as composition, not items={[...]} configuration

---

Detailed Resources

• examples/core.md - Compound parts, children-as-composition, context scoping, the collection/registry problem
• examples/state-contract.md - Controlled/uncontrolled hook, change details with reason and cancelation, state as data attributes
• examples/polymorphism.md - asChild/Slot, render/useRender, composeRefs, composeEventHandlers, merge rules
• examples/accessibility-structure.md - Id wiring, focus trap and restore, roving tabindex, typeahead
• reference.md - Prop-to-part translation, part and state naming, attribute vocabulary, ARIA and keyboard contracts

---

Philosophy

A composable component draws one line and never crosses it:

The component owns behavior, state and accessibility. The consumer owns markup, element type and styling.

Every defect this skill addresses is the same defect: the component reached across that line, and the API grew a prop to compensate. showCloseButton exists because the component decided to render a close button. padding="lg" exists because the component decided on spacing. renderItem exists because the component decided on item markup. Each one is a small piece of the consumer's job that the component took, then had to hand back through a narrow hole.

Composability is the opposite move: give the job back entirely. A Dialog.Close part is not a smaller showCloseButton -- it is the consumer rendering their own button, anywhere in the tree, with the close behavior attached to it.

The two current expressions of one principle. Element substitution is the clearest case of the line being respected, and two shapes for it are current:

Expression	Shape	Merging
asChild + Slot	<Trigger asChild><a href="/x">Docs</a></Trigger>	Clones the single child, merges props onto it
render prop	<Trigger render={<a href="/x">Docs</a>} />	Clones the given element, merges props onto it
render callback	render={(props, state) => <a {...props} />}	Hands you the props and the state; you place them

They are the same idea with different ergonomics. asChild reads as "this part IS this child"; render reads as "render this part AS this element", and its callback form additionally exposes the component's state so a consumer can branch on it. Neither is a fallback for the other -- a component ships one of them, consistently, on every part.

When to apply this skill:

• The component has more than about three boolean props
• A design change would require a new prop rather than different JSX
• The component renders markup the consumer did not ask for
• State lives only inside the component, or only outside it, but not both
• The component's own tests are the only place its keyboard behavior is described

When NOT to apply:

• The component has one call site and no reuse pressure -- configuration props are cheaper than parts
• The variation is genuinely closed (a type="button" | "submit" passthrough is not a boolean explosion)
• Splitting into parts would produce parts that can never be rearranged -- if Root > Header > Title is the only legal tree, title may honestly be a prop

---

Core Patterns

Pattern 1: Compound Components Over Configuration Props

A monolith accepts the whole component as data. A compound component accepts it as JSX: a Root that owns state and publishes it through context, and parts that subscribe. The consumer decides which parts exist, in what order, wrapped in what.

// Monolith: every new layout need becomes a new prop
<Dialog title="Delete" description="Permanent." showCloseButton size="lg" renderFooter={renderActions} />

// Compound: layout is JSX, the component still owns behavior
<Dialog.Root>
  <Dialog.Trigger>Delete</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Backdrop />
    <Dialog.Popup>
      <Dialog.Title>Delete</Dialog.Title>
      <Dialog.Close>Cancel</Dialog.Close>
    </Dialog.Popup>
  </Dialog.Portal>
</Dialog.Root>

Why good: A footer above the title, two close buttons, a form wrapping the popup -- all are rearrangements, not API changes. The Root still owns open state, dismissal, focus and aria-* wiring, so nothing accessible was traded away for the flexibility.

Why the monolith is bad: title forces the component to choose the heading level and its position. showCloseButton forces it to choose the button's markup, label and placement. renderFooter is children with a worse signature and no access to the parts' context. Each prop is a permanent commitment resolvable only by adding another prop.

Full before/after, including the context and part implementations: See examples/core.md.

---

Pattern 2: Controlled/Uncontrolled Duality

Every piece of state a component owns ships as a triple: value (controlled), defaultValue (uncontrolled initial), and onValueChange (always called, in both modes). The component is uncontrolled by default so the common case needs no state at all.

const [open, setOpen] = useControllableState({
  value: props.open,
  defaultValue: props.defaultOpen ?? false,
  onChange: props.onOpenChange,
});

Why good: One resolved value, one setter, one source of truth. onOpenChange fires in both modes, so analytics and side effects attach the same way regardless of who owns the state. A consumer converts from uncontrolled to controlled by adding two props, not by rewriting call sites.

Why the alternatives are bad: open with no onOpenChange produces a component that can never close itself -- the consumer must reimplement outside-press and Escape. useState(props.open) copies the prop once and then drifts silently. Mode-switching mid-life (value going from undefined to defined) changes which state wins between renders and desynchronizes the DOM; decide the mode at mount and warn if it changes.

The change-details argument. A bare (value) => void tells the consumer what changed but not why, and gives them no way to refuse. Passing a details object solves both:

onOpenChange={(open, details) => {
  if (details.reason === "outside-press" && hasUnsavedEdits) details.cancel();
}}

Why good: reason lets side effects be conditional (close-by-Escape and close-by-submit are different events). cancel() lets the consumer veto the state change without hoisting the state, which is the only alternative in a bare-callback API.

Full useControllableState implementation and details object: See examples/state-contract.md.

---

Pattern 3: Polymorphism -- asChild and render

A component that hardcodes its element type forces wrappers. A trigger that must be a link, a menu item that must be a router link, a heading whose level depends on nesting -- all need element substitution, and both current shapes work by cloning an element the consumer supplies and merging the component's props onto it.

// asChild form: the part becomes its child
import { Slot } from "radix-ui";

const Comp = asChild ? Slot.Root : "button";
return <Comp {...rest} ref={forwardedRef} />;

// render form: the part renders as the given element
import { useRender } from "@base-ui/react/use-render";
import { mergeProps } from "@base-ui/react/merge-props";

return useRender({
  defaultTagName: "button",
  render,
  props: mergeProps<"button">(internalProps, rest),
});

Why good: The consumer's element keeps its own semantics (<a href> stays a link, is focusable, and works with the router) while gaining the component's behavior, aria-* wiring and state attributes. No wrapper element is introduced, so layout and CSS selectors are unaffected.

The merging contract -- the part every implementation gets wrong. Substitution is only safe if all three are merged rather than overwritten:

What	Rule
Handlers	The consumer's handler runs first; the component's internal handler runs after and is skippable
Refs	Both refs receive the node -- the component needs it for measurement and focus restore
Class/style	Concatenated and shallow-merged, with the consumer's values winning on conflict

The escape hatch differs by library and this is the single most confusable fact in this area: with Slot-based composition the consumer calls event.preventDefault() and the primitive's composed handler checks defaultPrevented before running; with Base UI's merged props the consumer calls event.preventBaseUIHandler(), which skips Base UI's internal handler without calling preventDefault() or stopPropagation().

Why hand-rolled substitution is bad: React.cloneElement(child, props) overwrites the child's onClick, drops the child's ref, and replaces className instead of concatenating. The result renders fine, passes type-check, and silently breaks the consumer's handler.

Both APIs in full, plus dependency-free composeRefs/composeEventHandlers: See examples/polymorphism.md.

---

Pattern 4: State as data-* Attributes, Zero Visual Opinions

Every state the component computes is published on the DOM as a data attribute. Styling then happens in the consumer's stylesheet against [data-state="open"] or [data-disabled] -- no state needs to travel back out through props.

<button
  data-state={open ? "open" : "closed"}
  data-side={side}
  {...(disabled ? { "data-disabled": "" } : null)}
/>

Why good: Enumerated states become attribute values (data-state="open" | "closed"), boolean states become attribute presence. The consumer styles hover, open and disabled without the component knowing a single class name, and without re-rendering on every visual state change.

// Bad: a boolean state written as a value
<button data-disabled={disabled} /> // renders data-disabled="false"

Why bad: [data-disabled] matches an element whose attribute is the string "false", so every disabled style applies to enabled elements. Attribute presence is the boolean; omit the attribute entirely when the state is off.

Zero visual opinions. A behavior part renders no default className, no colors, no spacing, no transitions. The only styles it may set inline are the ones that are functionally load-bearing -- computed position coordinates, transform for a thumb, measured sizes -- and even those belong in CSS custom properties where possible, so the consumer can override them.

Full attribute vocabulary, state-driven className/style functions, and exit-animation attributes: See examples/state-contract.md.

---

Pattern 5: Prop Forwarding Discipline

A part is a DOM element with behavior attached. Anything the consumer puts on it -- id, aria-label, data-testid, className, onKeyDown, tabIndex -- must reach the DOM node. Destructure only what you consume; spread the rest.

<button
  type="button" // default: overridable
  {...rest} // consumer's props
  ref={composeRefs(forwardedRef, localRef)} // non-negotiable
  aria-expanded={open}
  data-state={open ? "open" : "closed"}
  onClick={composeEventHandlers(rest.onClick, handleClick)}
/>

Why good: Ordering encodes intent. Defaults sit before the spread so the consumer can override them. Non-negotiables -- the composed ref, the aria-* wiring, the composed handlers -- sit after the spread so a stray prop cannot silently break accessibility. Nothing the consumer passes is swallowed.

// Bad: an allowlist API pretending to be a DOM element
function Trigger({ children, onClick }: TriggerProps) {
  return <button onClick={onClick}>{children}</button>;
}

Why bad: id, className, aria-label, data-testid and every other prop vanish with no error. Consumers add a wrapper <div> to attach what they need, which breaks the CSS selectors and the flex/grid layout the trigger was sitting in. The ref never arrives, so focus restore and positioning measurement fail.

Ref forwarding across React versions and the full composition helpers: See examples/polymorphism.md.

---

Pattern 6: Context Scoping and Clear Out-of-Root Errors

Parts communicate with their Root through a context created per-primitive and provided per-Root instance -- never a module-level store. Reading that context is always guarded, and the guard names the part.

const DialogContext = createContext<DialogContextValue | null>(null);

function useDialogContext(part: string): DialogContextValue {
  const context = useContext(DialogContext);
  if (context === null) {
    throw new Error(`<Dialog.${part}> must be rendered inside <Dialog.Root>.`);
  }
  return context;
}

Why good: The null default makes misuse impossible to miss, and the message names both the offending part and the fix. Two dialogs on the same page have two providers, so nesting resolves by React's normal context shadowing rather than by an id-matching scheme.

Why a default value object is bad: createContext(defaultValue) makes an orphaned Dialog.Close render a button that does nothing -- no error, no warning, and a bug that only shows up in manual testing. Silent no-ops are worse than crashes in a component library.

Memoize the value. The context value is rebuilt every render unless memoized, and every part re-renders with it. Memoize on the state it actually contains, and keep setters stable with useCallback or useRef so they are not part of the dependency list.

Full provider, per-part consumers, and the descendant-registry pattern: See examples/core.md.

---

Pattern 7: Structural Accessibility

Accessibility that depends on the consumer passing the right aria-* props is accessibility that will be wrong. A composable component wires it structurally: it generates ids, connects them across parts through context, and owns the keyboard and focus behavior its role requires.

// Title generates its id and registers it with the Root; Popup consumes it,
// and renders no aria-labelledby at all when no Title is present.
const generatedId = useId();
const id = props.id ?? generatedId;

useEffect(() => {
  registerTitleId(id);
  return () => registerTitleId(undefined);
}, [id, registerTitleId]);

Why good: The relationship survives every rearrangement of the parts, because it flows through context rather than through the DOM tree the consumer wrote. Registration also means the attribute is absent when the part is absent, instead of pointing at an id that never rendered.

What "structural" covers, per role:

Concern	Owned by the component
Labeling	Generated ids, aria-labelledby/aria-describedby wired via context
Focus	Move focus in on open, restore to the trigger on close, trap while modal
Arrow keys	Roving tabindex -- exactly one item is tabbable, arrows move the active one
Typeahead	Buffered printable characters, matched against item text, reset on idle
Escape hatches	onOpenAutoFocus/onCloseAutoFocus-style hooks so consumers redirect focus without forking

Why bad without it: A dialog that does not restore focus leaves the keyboard user at the top of the document. A listbox that makes every option tabbable turns one Tab press into forty. Neither is visible in a screenshot, and neither is the consumer's job to discover.

Id registration, focus trap and restore, roving tabindex and typeahead implementations: See examples/accessibility-structure.md.

---

Pattern 8: Children as Composition, Not items={[...]}

An items array makes the component responsible for rendering every item, which means it is responsible for icons, badges, descriptions, grouping, empty states, keys and i18n -- forever, one prop at a time. Children hand all of it back.

// Config: the component owns item markup, so every design need is a new prop
<Select items={options} renderItem={renderOption} groupBy="category" showIcons />

// Composition: the consumer owns markup, the component still owns behavior
<Select.Popup>
  <Select.Group>
    <Select.GroupLabel>Frameworks</Select.GroupLabel>
    <Select.Item value="react">React <Badge>new</Badge></Select.Item>
  </Select.Group>
</Select.Popup>

Why good: Anything renderable is an item's content. Grouping is markup rather than a groupBy string. The component keeps ownership of selection, keyboard navigation and aria-activedescendant, because each Item registers itself with the Root.

The cost, stated honestly: with an items array the component knows the order for free; with children it must build a registry. Register each item's DOM node on mount and sort the registry by compareDocumentPosition, never by mount order -- mount order and DOM order diverge under conditional rendering, portals and Suspense, and index-based registration silently misroutes arrow keys after any reorder.

Item registry, DOM-order sorting, and the value/label problem: See examples/core.md.

---

Scope Boundaries

This skill is about the shape of a component's API. It is deliberately not about:

Out of scope	Belongs to
Using the primitive libraries themselves	web-ui-radix-ui, web-ui-base-ui
WCAG conformance, screen reader testing at large	web-accessibility-web-accessibility
Variant styling and class composition	web-styling-cva
Design tokens, theming, color systems	their own styling skills

Accessibility appears here only where it is structural -- id wiring, focus ownership, keyboard behavior -- because those decisions are API decisions: they determine what parts exist and what context they share. Contrast ratios, alt text and audit workflows are not.

Styling appears here only as a contract -- what a component must expose (data-*, className passthrough, CSS custom properties) so that styling is possible at all. Which styling tool consumes that contract is not this skill's concern.

---

<red_flags>

RED FLAGS

High Priority Issues: