Vercel Composition Patterns

React Composition Patterns

Concept of the skill

This skill is the discipline of growing a React component's API by composition instead of by accumulating boolean flags. Its central move is the boolean state-explosion audit: before any prop is added, you count how many booleans a component already has, how many combined states that produces (2ⁿ), and how many of those combinations are impossible, unsupported, or contradictory — because the answer almost always reveals that the component's real shape is a small set of named valid variants, not the cartesian product of its flags. From that audit follow the patterns that scale: compound components (a family like Tabs.List / Tabs.Tab / Tabs.Panel that share state through a context provider rather than through prop drilling), explicit variant components (named modes instead of flag combinations), children-over-render-props (composing structure through children rather than renderX callbacks), and the provider state/actions/meta interface (one place owns the canonical state, the actions that mutate it, and the derived meta, decoupling consumers from how state is managed). The skill also carries the React 19 API migration — ref as a regular prop instead of forwardRef, and use() in place of useContext(). The throughline is restraint enforced by measurement: provider boundaries matter more than visual nesting, and a boolean prop is a cost to be justified against the audit, never a default reflex.

Coverage

React component composition patterns that prevent boolean prop proliferation: compound components (shared-context child families), explicit variant components, children-over-render-props, the context provider state/actions/meta interface, the boolean state explosion audit, and the React 19 API migration (ref as a regular prop instead of forwardRef, use() over useContext()). Covers the refactor playbook from flag inventory through impossible-state deletion and variant extraction to provider-based composition.

The rule categories, in priority order:

1. Component Architecture (HIGH)

• architecture-avoid-boolean-props — don't add boolean props to customize behavior; use composition.
• architecture-compound-components — structure complex components with shared context (a parent provides state; named children consume it).
• architecture-boolean-state-audit — count reachable vs impossible states before adding props.

2. State Management (MEDIUM)

• state-decouple-implementation — the provider is the only place that knows how state is managed.
• state-context-interface — define a generic interface with state, actions, and meta for dependency injection.
• state-lift-state — move state into provider components so siblings can access it without prop drilling.

3. Implementation Patterns (MEDIUM)

• patterns-explicit-variants — create explicit variant components instead of boolean modes.
• patterns-children-over-render-props — use children for composition instead of renderX props.

4. React 19 APIs (MEDIUM)

⚠️ React 19+ only. Skip this section on React 18 or earlier.

• react19-no-forwardref — don't use forwardRef; pass ref as a regular prop, and use use() instead of useContext().

Boolean State Explosion Audit

Before adding a new prop or mode, answer:

1. How many booleans does this component already have?
2. How many combined states does that create (2ⁿ)?
3. Which of those states are impossible, unsupported, or nonsensical?
4. Can the valid states be named as explicit variants instead?

If a boolean produces impossible combinations, stop and refactor the API.

Refactor Playbook

1. Inventory flags and modes.
2. Enumerate valid combinations.
3. Delete impossible states.
4. Name the remaining variants explicitly.
5. Extract a provider that owns state, actions, and meta.
6. Compose subcomponents around that contract.
7. Add one example or test per valid variant.

Philosophy of the skill

Boolean props are technical debt that compounds exponentially. Every boolean added to a component doubles the state space, and most of those combined states are impossible or unsupported. Agents default to adding "just one more boolean" because it is the fastest path — this skill forces the discipline of auditing the state explosion first. Without it, agents regularly create components with five-plus booleans and fragile if/else rendering chains that break on edge-case combinations.

Composition is the antidote: build flexible, maintainable React components by using compound components, lifting state, and composing internals rather than toggling behavior through flags. Provider boundaries matter more than visual nesting — the provider owns state, actions, and meta, and consumers compose around that contract. These patterns make codebases easier for both humans and AI agents to work with as they scale, because the valid configurations stay explicit and enumerable instead of hiding inside a cartesian product of flags.

The core mandate is short and strict:

• Never add boolean props to customize behavior.
• If a component accumulates three or more booleans, treat the API as broken until proven otherwise by the state-explosion audit.
• Provider boundaries matter more than visual nesting; the provider owns state, actions, and meta.

Verification

After applying this skill, verify:

• No component has 3+ boolean props without an explicit variant refactor.
• State is lifted into a context provider, not drilled through props.
• Compound components use children composition, not renderX props.
• React 19 code passes ref as a regular prop and uses use() instead of useContext().
• Impossible state combinations are documented and eliminated (the audit's "delete impossible states" step is reflected in the code).
• Each valid variant has at least one example or test, so the enumerated states are exercised rather than assumed.

Do NOT Use When