1---
2name: vercel-composition-patterns
3description:
4  React composition patterns that scale. Use when refactoring components with
5  boolean prop proliferation, building flexible component libraries, or
6  designing reusable APIs. Triggers on tasks involving compound components,
7  render props, context providers, or component architecture. Includes React 19
8  API changes.
9license: MIT
10metadata:
11  author: vercel
12  version: '1.0.0'
13---
14 
15# React Composition Patterns
16 
17Composition patterns for building flexible, maintainable React components. Avoid
18boolean prop proliferation by using compound components, lifting state, and
19composing internals. These patterns make codebases easier for both humans and AI
20agents to work with as they scale.
21 
22## When to Apply
23 
24Reference these guidelines when:
25 
26- Refactoring components with many boolean props
27- Building reusable component libraries
28- Designing flexible component APIs
29- Reviewing component architecture
30- Working with compound components or context providers
31 
32## Rule Categories by Priority
33 
34| Priority | Category                | Impact | Prefix          |
35| -------- | ----------------------- | ------ | --------------- |
36| 1        | Component Architecture  | HIGH   | `architecture-` |
37| 2        | State Management        | MEDIUM | `state-`        |
38| 3        | Implementation Patterns | MEDIUM | `patterns-`     |
39| 4        | React 19 APIs           | MEDIUM | `react19-`      |
40 
41## Quick Reference
42 
43### 1. Component Architecture (HIGH)
44 
45- `architecture-avoid-boolean-props` - Don't add boolean props to customize
46  behavior; use composition
47- `architecture-compound-components` - Structure complex components with shared
48  context
49 
50### 2. State Management (MEDIUM)
51 
52- `state-decouple-implementation` - Provider is the only place that knows how
53  state is managed
54- `state-context-interface` - Define generic interface with state, actions, meta
55  for dependency injection
56- `state-lift-state` - Move state into provider components for sibling access
57 
58### 3. Implementation Patterns (MEDIUM)
59 
60- `patterns-explicit-variants` - Create explicit variant components instead of
61  boolean modes
62- `patterns-children-over-render-props` - Use children for composition instead
63  of renderX props
64 
65### 4. React 19 APIs (MEDIUM)
66 
67> **⚠️ React 19+ only.** Skip this section if using React 18 or earlier.
68 
69- `react19-no-forwardref` - Don't use `forwardRef`; use `use()` instead of `useContext()`
70 
71## How to Use
72 
73Read individual rule files for detailed explanations and code examples:
74 
75```
76rules/architecture-avoid-boolean-props.md
77rules/state-context-interface.md
78```
79 
80Each rule file contains:
81 
82- Brief explanation of why it matters
83- Incorrect code example with explanation
84- Correct code example with explanation
85- Additional context and references
86 
87## Full Compiled Document
88 
89For the complete guide with all rules expanded: `AGENTS.md`
90