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
| Priority | Category | Impact | Prefix |
|---|
| 1 | Component Architecture | HIGH | INLINECODE0 |
| 2 |
State Management | MEDIUM |
state- |
| 3 | Implementation Patterns | MEDIUM |
patterns- |
| 4 | React 19 APIs | MEDIUM |
react19- |
Quick Reference
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
2. State Management (MEDIUM)
- -
state-decouple-implementation - Provider is the only place that knows how
state is managed
- -
state-context-interface - Define generic interface with state, actions, meta
for dependency injection
- -
state-lift-state - Move state into provider components for sibling access
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 if using React 18 or earlier.
- -
react19-no-forwardref - Don't use forwardRef; use use() instead of INLINECODE14
How to Use
Read individual rule files for detailed explanations and code examples:
CODEBLOCK0
Each rule file contains:
- - Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references
Full Compiled Document
For the complete guide with all rules expanded: INLINECODE15
React 组合模式
用于构建灵活、可维护的 React 组件的组合模式。通过使用复合组件、状态提升和内部组合，避免布尔属性泛滥。这些模式使代码库在扩展时更易于人类和 AI 代理协作。
何时应用
在以下情况下参考这些指南：
- - 重构包含大量布尔属性的组件
- 构建可复用的组件库
- 设计灵活的组件 API
- 审查组件架构
- 处理复合组件或上下文提供者
按优先级分类的规则
| 优先级 | 类别 | 影响 | 前缀 |
|---|
| 1 | 组件架构 | 高 | architecture- |
| 2 |
状态管理 | 中 | state- |
| 3 | 实现模式 | 中 | patterns- |
| 4 | React 19 API | 中 | react19- |
快速参考
1. 组件架构（高）
- - architecture-avoid-boolean-props - 不要添加布尔属性来自定义行为；应使用组合
- architecture-compound-components - 使用共享上下文构建复杂组件
2. 状态管理（中）
- - state-decouple-implementation - 提供者是唯一知道状态管理方式的地方
- state-context-interface - 定义包含状态、操作、元数据的通用接口，用于依赖注入
- state-lift-state - 将状态移至提供者组件中，以便兄弟组件访问
3. 实现模式（中）
- - patterns-explicit-variants - 创建显式变体组件，而非使用布尔模式
- patterns-children-over-render-props - 使用 children 进行组合，而非 renderX 属性
4. React 19 API（中）
⚠️ 仅适用于 React 19 及以上版本。 如果使用 React 18 或更早版本，请跳过此部分。
- - react19-no-forwardref - 不要使用 forwardRef；使用 use() 替代 useContext()
如何使用
阅读各个规则文件以获取详细说明和代码示例：
rules/architecture-avoid-boolean-props.md
rules/state-context-interface.md
每个规则文件包含：
- - 为何重要的简要说明
- 带解释的错误代码示例
- 带解释的正确代码示例
- 额外上下文和参考资料
完整编译文档
如需包含所有规则扩展的完整指南：AGENTS.md
