--- name: meta-design-composable-components description: Composable component APIs — parts, state, polymorphism. Load when designing a reusable component's API, or aligning one that has grown boolean, renderX or style props. --- # Composable Component Patterns > **Quick Guide:** The component owns behaviour, state and accessibility; the consumer owns markup, element type and styling. That line settles most API questions: variation becomes parts and children instead of booleans and `renderX` props, each exposed state ships as `value` + `defaultValue` + `onValueChange` with a details argument carrying the reason and a veto, every part can render as the consumer's element through one substitution shape, state is published as `data-*` attributes, and whatever the consumer passes — props, handlers, refs — is composed rather than replaced. Three React 19 facts change the code: `ref` is an ordinary prop, a callback ref may return a cleanup that a ref-composing helper has to collect, and `useId`'s format changed in both 19.1 and 19.2, with only 19.2's safe in both a CSS selector and an XML id. **Detailed Resources:** - [examples/core.md](examples/core.md) — Patterns 1–3: compound parts, children with a descendant registry, context scoping - [examples/state-contract.md](examples/state-contract.md) — Patterns 4–5: `useControllableState`, change details with reason and cancel, retrofitting the triple, state as `data-*` attributes - [examples/polymorphism.md](examples/polymorphism.md) — Patterns 6–7: `asChild` and `render` built without a library, the merge they share, `composeEventHandlers`, `composeRefs`, prop ordering - [examples/accessibility-structure.md](examples/accessibility-structure.md) — Pattern 8: id wiring, focus ownership, roving tabindex, typeahead, Escape - [reference.md](reference.md) — prop-to-part translation, naming tables, substitution merge rules, attribute vocabulary, ARIA and keyboard contracts, the alignment checklist --- ## Which path applies - **Designing a new component** — settle the parts (Patterns 1–3), then the state contract (4–5); substitution and forwarding (6–7) apply to every part you defined. Start at [examples/core.md](examples/core.md). - **Aligning an existing component** — read its call sites, run it through the [alignment checklist](reference.md#alignment-checklist), and fix API shape first, because the later axes depend on which parts exist. Migrate additively, as [retrofitting the triple](examples/state-contract.md#retrofitting-an-existing-component) shows. - **Building on a headless library that already ships parts** — use its substitution shape and its merge helper on every part you add, so yours behave like its own; the library's API is its own skill's subject, and [examples/polymorphism.md](examples/polymorphism.md) shows what any merge has to guarantee. --- ## Before designing a component API **Express variation as parts and children, never as configuration props.** A boolean or `renderX` prop is the component deciding the consumer's markup, so each design need becomes another prop and N booleans become 2^N layouts to render and test; a part lets the consumer's JSX make that decision once. **Ship every exposed piece of state as `value` + `defaultValue` + `onValueChange`, resolved in one hook.** A controlled prop copied into `useState` is read once and then drifts from the consumer's store; resolving to the prop whenever it is defined leaves no second copy to drift. **Compose what the consumer passes — props, handlers, refs — instead of replacing it.** Defaults go before the rest-spread and wiring after it, the consumer's handler runs first, and refs are merged; anything replaced disappears with no error and no type failure. **Publish every state as a `data-*` attribute, and ship behaviour parts with no visual styling.** Attribute selectors let consumers style each state without the component knowing a class name or re-rendering; a default class, colour or transition is something every consumer has to out-specify. **Read every call site before changing a component's API.** A removed prop whose name is also an HTML attribute — `title`, `hidden`, `color` — still type-checks once a part extends its element's props, and lands on the DOM node instead of failing the build. --- **Auto-detection:** compound components, namespaced parts, `asChild`, `render` prop, `useControllableState`, `defaultValue`, `onValueChange`, `onOpenChange`, change details, `data-state`, `data-disabled`, `composeRefs`, `composeEventHandlers`, out-of-Root error, descendant registry, roving tabindex, typeahead, focus trap, polymorphic component, boolean prop explosion, `renderX` props, `items` prop, headless component **Applies to:** - Deciding whether a new requirement becomes a prop, a part or children - Designing the public API of a reusable component - Aligning a component that has accumulated booleans, `renderX` props, style props or an `items` array - Adding controlled/uncontrolled support, with a change callback that says why and can be refused - Letting a part render as the consumer's element, and composing their props, handlers and refs onto it - Publishing state for styling, and wiring ids, focus and keyboard behaviour across parts - Reviewing a component change for API shape and forwarding discipline **Handled elsewhere:** - A headless library's own API — its parts, props, merge helper, escape hatch and version facts — is covered by that library's own skill. This skill settles the shape of what you build, on top of a library or without one. - Which headless library to adopt. - Accessibility conformance — WCAG audits, contrast, alt text, screen-reader testing. Accessibility appears here only where it decides which parts exist and what they share. - Authoring styles — variant composition, tokens, theming. Styling appears here only as the contract a component exposes: `data-*` attributes, `className` and `style` passthrough, CSS custom properties. - Visual design — spacing scales, colour systems, variant naming. --- ## Philosophy A composable component draws one line and keeps to it: > **The component owns behaviour, state and accessibility. The consumer owns markup, element type and styling.** Every defect this skill addresses is the component reaching across that line, and the API growing a prop to hand the job back through a narrow hole. `showCloseButton` exists because the component decided to render a close button, `padding="lg"` because it decided on spacing, `renderItem` because it decided on item markup. Composability hands the job back whole: `Dialog.Close` is not a smaller `showCloseButton` — it is the consumer's own button, anywhere in the tree, with close behaviour attached. --- ## Decision Framework ### Prop, part or children? ``` Does the requirement change what is RENDERED? |-- NO (it changes behaviour or state) -> A prop. +-- YES -> Can the consumer already express it by rearranging existing parts? |-- YES -> Add nothing. Document the arrangement. +-- NO -> Does it need the component's state or behaviour attached? |-- YES -> A PART: a new subcomponent reading the shared context. +-- NO -> The consumer's markup. Accept it as children. ``` A boolean prop is right only when it changes behaviour (`modal`, `disabled`, `loop`), never when it toggles markup. ### Controlled, uncontrolled or both? ``` Does anything outside the component need to read or set this state? |-- NEVER -> Keep it internal; expose nothing. |-- SOMETIMES -> The triple: value + defaultValue + onValueChange. | Uncontrolled by default, controlled when `value` is defined. +-- ALWAYS (the component cannot compute it) -> Required value + onValueChange, no defaultValue, documented as controlled-only. ``` `value` alone cannot change and `defaultValue` alone cannot be observed, so neither ships without `onValueChange`. ### Which substitution shape? ``` Does the library you are extending already define one? |-- YES -> That one, on every part. +-- NO -> Do consumers need the component's STATE to choose what to render? |-- YES -> render={(props, state) => ...} +-- NO -> asChild, or render={}. Pick one: the value is that every part works alike. ``` ### When configuration props are the right answer - One call site and no reuse pressure — props are cheaper than parts. - The variation is closed: a `type="button" | "submit"` passthrough is not a boolean explosion. - The parts could never be rearranged — if `Root > Header > Title` is the only legal tree, `title` may honestly be a prop. - A layout container that genuinely takes no state and no variation — it takes children and nothing else, so there are no parts to split and no state to expose. --- ## Core patterns ### Pattern 1: Compound Parts Over Configuration Props A `Root` owns state and publishes it through context; parts subscribe, and the consumer decides which parts exist, in what order, wrapped in what. ```tsx // Monolith: each layout need is a new prop // Parts: layout is JSX; Root still owns open state, dismissal, focus and aria-* wiring Delete Delete Cancel ``` Full code: [examples/core.md](examples/core.md#pattern-1-compound-parts-over-configuration-props) ### Pattern 2: Children as Composition An `items` array makes the component own every item's markup — icons, badges, grouping, empty states — one prop at a time. Children hand that back while each `Item` registers with the `Root`, which keeps selection, keyboard navigation and `aria-activedescendant`. The cost is a registry ordered by DOM position, since mount order stops matching DOM order the first time an item renders late. ```tsx Frameworks React new ``` Full code: [examples/core.md](examples/core.md#pattern-2-children-as-composition) ### Pattern 3: Context Scoping One context per primitive, provided per `Root`, created with a `null` default and read through a guard that names the part — so an orphaned part throws instead of rendering a button that does nothing. ```tsx const DialogContext = createContext(null); function useDialogContext(part: string): DialogContextValue { const context = useContext(DialogContext); if (context === null) throw new Error(` must be rendered inside .`); return context; } ``` Memoize the provided value — by hand, or with the React Compiler running over the component's source — or every part re-renders on every `Root` render. Full code: [examples/core.md](examples/core.md#pattern-3-context-scoping) ### Pattern 4: Controlled and Uncontrolled State One hook resolves the triple to a single value and setter, and calls `onValueChange` in both modes, so consumer side effects attach the same way whoever owns the state. The callback's second argument says why the change happened and lets the consumer refuse it without taking control. ```tsx const [isOpen, setIsOpen] = useControllableState({ value: open, defaultValue: defaultOpen, onChange: onOpenChange, componentName: "", }); { if (details.reason === "outside-press" && hasUnsavedEdits) details.cancel(); }} />; ``` Full code: [examples/state-contract.md](examples/state-contract.md#pattern-4-controlled-and-uncontrolled-state) ### Pattern 5: State as Data Attributes Enumerated states are attribute values, boolean states are attribute presence, and the consumer's stylesheet does the rest. Behaviour parts set no class, colour, spacing or transition; the only inline styles they may set are functionally load-bearing — computed coordinates, measured sizes — exposed as CSS custom properties where possible, so the consumer's stylesheet decides how they apply and can override them. ```tsx