Designing a component API
The surface a reusable component offers: the props it takes, the events it fires, and the parts callers can replace. A strong answer keeps behavior inside the component and hands rendering and styling to the caller.
What it is
A component's API is the contract between the people who build it and the people who drop it into a page. A useful way to read it is in three parts. Data and configuration flow in as props. Events flow out as callbacks the caller provides. And there are extension points: places where the caller supplies markup or behavior the component doesn't know about in advance. In React, props are immutable snapshots, and a new render brings a new set, so a component that needs interactivity keeps state rather than mutating what it was given. The simplest extension point is children: whatever is nested inside the tag arrives as a prop, and the component renders it in place without knowing what it is. React's documentation describes this as a hole the parent fills with arbitrary JSX.
The second design decision is who owns the state. A component with its own local state is called uncontrolled: its parent can't steer it. One whose important values come from props is controlled: the parent decides, and the component reports changes through callbacks. Uncontrolled components are easier to drop in because they need less setup; controlled ones are more flexible but push the configuration onto the parent. Most real components mix the two, so the question to answer for each value (the typed text, the open state, the highlighted row) is whether a caller will ever need to drive it from outside.
The third decision is how callers customize what they see. The tempting route is a prop per request: showImage, subtitle, variant="people". Kent C. Dodds lists what that costs as requests pile up: more code shipped to the device, more surface to maintain, branches that interact with each other, and documentation each caller must read to find the one option they need. The alternative is inversion of control: instead of the component deciding what to render from flags, the caller supplies the rendering, and the component supplies the data and behavior. The forms the article shows are compound components (a Menu with MenuButton and MenuItem parts the caller arranges), render props, and a stateReducer prop on an autocomplete library that let callers change state transitions, after which requests for new customization options fell sharply.
// Example API for a shared autocomplete box.
type Item = { id: string; label: string };
type AutocompleteProps<T extends Item> = {
// Data in, events out
fetchItems: (query: string, signal: AbortSignal) => Promise<T[]>;
onSelect: (item: T) => void;
query?: string; // pass it to control the text from outside
defaultQuery?: string; // or let the box keep its own
onQueryChange?: (query: string) => void;
// The hole each team fills; the box wraps it in an option with role, id and focus
renderItem?: (item: T, state: { active: boolean }) => React.ReactNode;
// Looks, not structure
className?: string;
};
// Products team: a picture and a name
<Autocomplete<Product>
fetchItems={searchProducts}
onSelect={openProduct}
renderItem={(p) => (
<>
<img src={p.thumbnail} alt="" />
<span>{p.label}</span>
</>
)}
/>
// Plain-text team: no renderItem, the box falls back to item.label
<Autocomplete fetchItems={searchHelp} onSelect={openArticle} />The same ideas exist outside React. A web component with a shadow tree exposes slot elements: a slot with a name attribute is filled by light-DOM children carrying a matching slot attribute, children with no slot attribute land in the unnamed slot, and whatever the template puts inside the slot element shows as fallback when the caller supplies nothing. For styling, an element inside the shadow tree marked with a part attribute can be targeted from outside with ::part(name). Parts are visible to the parent document, not to further ancestors, so a nested component re-exposes them with exportparts.
When to use it
Reach for a rendering hole when more than one caller needs a different look for the same behavior. In the autocomplete case, the box keeps the debounce, the request, keyboard navigation, the active item and the ARIA wiring (see Accessible widgets for what that wiring is), and asks the caller for one thing: given this result, what should the row contain? A renderItem function fits a list the component owns, because the component has the data and the caller has the markup. Plain children fits a frame around caller content, such as a panel or a card. React's own guidance points the same way: forwarding all props with spread syntax in component after component usually means the pieces should be split and content passed as children instead.
Offer controlled props when a parent will coordinate the value with something else: the typed text mirrored into the URL, a filter panel that resets the box, two inputs kept in sync. The pattern is a value prop plus a change callback, with the parent holding the state. Keep an uncontrolled default for callers who just want the box to work: a defaultQuery the box copies into its own state once. Decide per value, since a component is usually a mix of both.
Let callers swap the rendered element when they have their own buttons and links. Radix Primitives do this with an asChild prop: the part renders no element of its own and instead clones its child, passing along the props and handlers that make it work. The caller's component has to spread those props onto its DOM node and forward a ref, or the behavior breaks, and the caller takes on the accessibility of the element they chose. A Tooltip.Trigger renders a button by default; swapping in a div loses keyboard focus.
Give a styling hook that changes appearance without changing structure: a className on the root, CSS variables for colors and spacing, or part names when the markup lives in a shadow tree. These cover the common case where three teams want the same rows in three palettes, and they're far cheaper than three render functions.
When not to
Don't invert control for a single caller. Dodds closes his article with that caution: a filter that drops nothing but null and undefined gets no value from a predicate argument, just more code to read. If one team uses your box today, a plain prop with a short list of values is the right API; add the hole when the second team with a different look shows up, since you'll know its shape then.
Don't hand over the parts that have to stay consistent. If callers render the whole list rather than one row, the box has to pass out the active state, the option ids and the refs it needs, and trust each caller to wire them correctly; a missed id or role shows up as a broken screen reader experience on one team's page but not another's. Radix makes the same point about swapping element types: once the caller picks the element, keeping it focusable and accessible is their job. Keep the row wrapper, the roles and the key handling inside, and open a hole for the row's contents.
Don't make everything controlled. A box whose text, open state and active item all have to be supplied from outside forces each caller to write state and handlers before anything works, which is the configuration cost the React docs attach to controlled components. Control the values a parent plausibly coordinates, and keep the rest as internal state with a callback so the parent can observe it.
Compared
| Technique | What the caller gets | Reach for it when | What it costs |
|---|---|---|---|
Plain prop ( | A value the component interprets | One caller, or variations from a short known list | A new prop and a branch for each new case |
| A hole filled with arbitrary markup | The caller brings the content and the component brings the frame | The component treats the content as opaque |
Render function ( | Per-item markup built from the component's data | The component owns the list and data; callers own each row's look | Callers learn the function's arguments, which become a contract |
Compound components | Named parts the caller arranges | Structure differs between callers, like a divider between items | More exports to learn; callers can arrange parts wrongly |
| The component's behavior on the caller's own element | Callers have their own buttons and links | The caller must spread props, forward a ref and keep the element accessible |
Controlled value | State driven from outside through a prop and a callback | A parent coordinates the value with something else | Each caller holds and updates the state |
Styling hooks ( | A new look on the same structure | Same rows, different theme | Callers depend on internal class or part names |
In a picture
Step 1 of 3
The box owns the behavior
Typing goes into the box. The box debounces, sends the request and holds the results. In this design, the team supplies no code for this step.