Composition Patterns

React Composition Patterns

Composition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.

When to Apply

Reference these guidelines when:

• Refactoring components with many boolean props
• Building reusable component libraries
• Designing flexible component APIs
• Reviewing component architecture
• Working with compound components or context providers

Rule Categories by Priority

Quick Reference

1. Component Architecture (HIGH)

Fundamental patterns for structuring components to avoid prop proliferation and enable flexible composition.

• architecture-avoid-boolean-props - Don't add boolean props to customize
• architecture-compound-components - Structure complex components with shared

2. State Management (MEDIUM)

Patterns for lifting state and managing shared context across composed components.

• state-context-interface - Define generic interface with state, actions, meta
• state-decouple-implementation - Provider is the only place that knows how
• state-lift-state - Move state into provider components for sibling access

3. Implementation Patterns (MEDIUM)

Specific techniques for implementing compound components and context providers.

• patterns-children-over-render-props - Use children for composition instead
• patterns-explicit-variants - Create explicit variant components instead of

4. React 19 APIs (MEDIUM)

React 19+ only. Don't use forwardRef; use use() instead of useContext().

• react19-no-forwardref - Don't use forwardRef; use use() instead of useContext()

How to Use

Read individual rule files for detailed explanations and code examples:

rules/architecture-avoid-boolean-props.md
rules/state-context-interface.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and references

Deep guides (read on demand, do not preload)

Every rule id listed above maps to a self-contained file at rules/<rule-id>.md, each with its own bad/good code pair.

Read only the rule file matching your task — not the set:

rules/<rule-id>.md

Loading one ~60-line rule beats skimming a compiled monolith. Do not preload the directory.

Owned elsewhere

Composition is orthogonal to state placement — get both right or the pattern leaks:

• std-reactjs is scoped to Vite SPA work and owns what state goes where (Zustand vs TanStack Query vs local) → @skills/std-reactjs/references/state-placement.md. A compound component whose context holds server data has invented a second cache.
• std-nextjs owns the Server/Client boundary → @skills/std-nextjs/references/rendering.md. Context requires a Client Component, so reaching for a provider is a rendering decision before it is a composition one.

Section 4 is React 19+ only, and this repo only pins React 19 for Next.js (std-nextjs: "React 19 minimum"). The Vite SPA and React Native pin no React version here — read package.json before applying react19-no-forwardref, exactly as that rule already warns.