playbooks

home / skills / secondsky / claude-skills / react-composition-patterns

react-composition-patterns skill

/plugins/react-composition-patterns/skills/react-composition-patterns

This skill helps you refactor React components by applying composition patterns to reduce boolean props and design flexible, reusable APIs.

npx playbooks add skill secondsky/claude-skills --skill react-composition-patterns

Review the files below or copy the command above to add this skill to your agents.

Files (12)
SKILL.md
2.5 KB
---
name: react-composition-patterns
description: React composition patterns that scale. Use when refactoring components with boolean prop proliferation, building flexible component libraries, or designing reusable APIs. Triggers on tasks involving compound components, render props, context providers, or component architecture.
license: MIT
metadata:
  author: vercel
  version: '1.0.0'
---

# 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   | `architecture-` |
| 2        | State Management        | MEDIUM | `state-`        |
| 3        | Implementation Patterns | MEDIUM | `patterns-`     |

## 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

## 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

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

Overview

This skill documents React composition patterns that scale. It helps teams refactor components with boolean prop proliferation, design reusable component libraries, and create flexible, maintainable component APIs. The guidance targets compound components, render props, context providers, and component architecture decisions.

How this skill works

The skill inspects tasks and code related to component APIs and suggests composition-based alternatives to boolean props and ad-hoc toggles. It highlights high-priority architecture rules, medium-priority state management techniques, and practical implementation patterns with concrete rule names and intent. Each rule includes rationale, incorrect and correct examples, and integration guidance for provider-based state and compound components.

When to use it

  • Refactoring components that have many boolean props or mode flags
  • Designing or extending a component library to be flexible and future-proof
  • Reviewing component architecture for scalability and testability
  • Implementing compound components that share state via context providers
  • Creating explicit variants or API shapes instead of exposing many toggles

Best practices

  • Avoid boolean props; prefer composition or explicit variant components
  • Lift shared state into a provider so siblings can coordinate without prop drilling
  • Define a generic context interface with state, actions, and metadata for dependency injection
  • Favor compound components and shared context over scattered render props for complex UIs
  • Provide explicit, named subcomponents (variants) rather than single-component mode switches

Example use cases

  • Replace a Button with multiple booleans (primary, danger, link) by creating explicit variant components or subcomponents
  • Refactor a Modal with show/hide booleans and callbacks into a provider-driven compound Modal with Header, Body, Footer subcomponents
  • Build a Tabs system where TabList, Tab, and TabPanel share lifted state via a context provider
  • Create a Form library where field state and validation are managed by a Form provider and exposed via hooks and context
  • Convert mixed render-prop APIs into clearer children-first compound components for easier composition and readability

FAQ

Will adopting these patterns increase runtime bundle size?

Not necessarily. Composition often reorganizes code rather than adding heavy dependencies. Proper tree-shaking and small, focused modules keep bundle impact minimal.

How do I migrate an existing large component with many boolean props?

Start by identifying common groups of props that form logical variants, extract explicit variant subcomponents, lift shared state into a provider, and replace boolean flags with composition or controlled props incrementally.