Designing Component APIs

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

Component API

The props a component accepts and how it behaves: what other developers program against.

Controlled component

A component whose value comes from the value prop; the parent owns the state and every change goes through onChange.

Uncontrolled component

A component that keeps its own state, starting from defaultValue; the parent can listen but doesn't own it.

Configuration API

A component steered by many props (showX, xAlign, xItems).

Composition API

A component that accepts children or sub-components that the caller arranges.

Variant

One of a fixed set of named looks or behaviours, such as variant="danger".

Polymorphic component

A component that can render as a different element or component, usually through an as prop.

Slot / asChild

A pattern where a component renders its child instead of its own element and merges its props into it.

Escape hatch

A way for callers to go beyond what the component planned: className, ...rest, ref.

1. 1

   Make Tickets controlled

   In the Stepper example, add const [tickets, setTickets] = useState(1); to App and change the Tickets stepper to value={tickets} onChange={setTickets}. Predict: does the log change? Does the screen behave any differently?

   Now change it to onChange={() => {}}. Predict what the + button does, then check. A controlled component with a parent that never updates is frozen, exactly like an <input value="x" /> with no onChange.

2. 2

   Add a variant

   Add ghost: "btn-ghost" to VARIANTS and a .btn-ghost { background: transparent; color: #0b7285; } rule, then render <Button variant="ghost">Cancel</Button>. One map entry, no new if.

3. 3

   Break the className merge

   In Button, move className out of the destructuring so it stays in rest (remove it from the parameter list and from cx). Predict the Buy button's class list, then run. The caller's class replaced every design-system class.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   Name props like the platform. Event callbacks start with on (onChange, onSelect, onOpenChange) and the code that handles them inside starts with handle. Booleans read as facts: disabled, open, required (match the HTML names when the HTML idea exists, rather than inventing isDisabled). A callback that reports a new value should pass the value, not the DOM event, when there is no single DOM event behind it: onValueChange(3). Consistent names mean people can guess your API.

2. 2

   Controlled and uncontrolled. You met these for inputs in Topics 5.1 and 5.3 and for lifted state in Topic 6.3. A reusable component should support both. Uncontrolled: the caller passes defaultValue (a starting value) and the component keeps its own state. Controlled: the caller passes value and onChange, owns the state, and can refuse or change any update. The usual rule: if value is not undefined, the component is controlled. A small hook, often called useControllableState, holds this logic once for every component in your design system.

3. 3

   Composition over configuration. A configuration API answers every new need with another prop: <Card title subtitle icon footerButtons showDivider headerAlign ... />. Each prop is easy to add and impossible to remove, and the component becomes a maze of ifs. A composition API gives parts that callers arrange: <Card><Card.Header>…</Card.Header><Card.Body>…</Card.Body></Card>, or plain children. You built the mechanics (compound components with shared context) in Topic 10.5; here the point is the design choice: when the caller needs layout freedom, hand them pieces, not switches.

4. 4

   Variants turn style choices into a small, closed set of named options: variant="primary" | "secondary" | "danger" and size="sm" | "md". A variant names an intent (danger), not a colour (red), so a redesign changes one map instead of every call site. Libraries such as class-variance-authority (cva) and Tailwind Variants generate these class maps (Topic 11.3).

5. 5

   Polymorphism means one component can render as different elements. The as prop (<Button as="a" href="/docs">) swaps the tag while keeping the styles. The **asChild** idea (popularised by Radix UI's Slot) goes further: instead of rendering its own element, the component merges its props and classes into its single child, so <Button asChild><Link to="/docs">Docs</Link></Button> produces one router link that looks like a button, with no wrapper element. Typing as properly in TypeScript is covered in Topic 12.6.

6. 6

   Escape hatches are the ways a caller can do something you didn't plan for. Three matter most: accept className and merge it with yours (never replace yours); spread ...rest onto the root element so aria-*, data-*, id, title and native event handlers pass through; and forward ref to the root DOM node so callers can focus or measure it (in React 19 ref is an ordinary prop for function components, see Topic 19.8). Missing escape hatches are why teams fork components.

• ↔

  Supporting both controlled and uncontrolled modes doubles the behaviours to test, but it's what makes a component usable in both quick forms and complex screens.

• ↔

  Composition APIs are flexible but give callers more ways to build something inconsistent; design systems balance them with a few well-named variants and documented recipes.

• ↔

  Polymorphism (as, asChild) is powerful but harder to type and can produce invalid HTML (a <button> inside an <a>); keep it to components where it's clearly needed.

• I can name props consistently: on… for events, HTML names for booleans.

• I can build a component that works both controlled and uncontrolled.

• I can turn a configuration-heavy API into a composition API.

• I can implement variants, an as prop and the asChild slot idea.

• I can add the three escape hatches: merged className, ...rest and ref.