Generated banner for Vercel Composition Patterns
Generated logo for Vercel Composition Patterns

Vercel Composition Patterns

VercelOfficialCreated by vercel

  • Skill
  • Guidelines
  • Software development
  • MIT
  • No issues found

From the author

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. Includes React 19 API changes.
— the description by vercel

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured set of guidelines for building maintainable and flexible React components. It focuses on replacing boolean prop proliferation with advanced composition techniques such as compound components, context providers, and explicit variants. The guide is designed to help developers and AI agents refactor complex UI codebases, ensuring that component APIs remain clean and scalable, while also incorporating modern practices for React 19.

What it does

  • Provides architectural patterns to replace boolean prop chains with composition.
  • Defines best practices for implementing compound components and shared context.
  • Offers guidance on decoupling state management from component implementation.
  • Includes specific rules for leveraging React 19 APIs like the use hook.
  • Standardizes component design to improve readability for both humans and AI agents.

When to use it

  • When refactoring components suffering from excessive boolean prop usage.
  • During the design phase of reusable component libraries or design systems.
  • When architecting complex components that require shared state or context.
  • When updating existing codebases to align with React 19 standards.
  • During architectural reviews to ensure component flexibility and scalability.

Advantages

  • Reduces technical debt caused by complex, hard-to-maintain prop interfaces.
  • Promotes a modular architecture that is easier to test and extend.
  • Improves the developer experience by providing clear, predictable component APIs.
  • Ensures consistency across large-scale React applications.
  • Facilitates better integration with AI-assisted coding workflows.

Usage examples

“How can I refactor a button component that has too many boolean props like isPrimary, isLarge, and isDisabled?”
The agent will suggest replacing boolean props with explicit variant components or a composition-based approach to simplify the API.
“Explain how to use compound components for a modal system.”
The agent will provide a structure using context providers to share state between the modal trigger, header, and body components.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/vercel-labs/vercel-composition-patterns/download
  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip vercel-composition-patterns.zip -d .agents/skills

Documentation by vercel

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

PriorityCategoryImpactPrefix
1Component ArchitectureHIGHarchitecture-
2State ManagementMEDIUMstate-
3Implementation PatternsMEDIUMpatterns-
4React 19 APIsMEDIUMreact19-

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

Full Compiled Document

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

Files

rules/state-context-interface.md


title: Define Generic Context Interfaces for Dependency Injection impact: HIGH impactDescription: enables dependency-injectable state across use-cases tags: composition, context, state, typescript, dependency-injection

Define Generic Context Interfaces for Dependency Injection

Define a generic interface for your component context with three parts: state, actions, and meta. This interface is a contract that any provider can implement—enabling the same UI components to work with completely different state implementations.

Core principle: Lift state, compose internals, make state dependency-injectable.

Incorrect (UI coupled to specific state implementation):

function ComposerInput() {
  // Tightly coupled to a specific hook
  const { input, setInput } = useChannelComposerState()
  return <TextInput value={input} onChangeText={setInput} />
}

Correct (generic interface enables dependency injection):

// Define a GENERIC interface that any provider can implement
interface ComposerState {
  input: string
  attachments: Attachment[]
  isSubmitting: boolean
}

interface ComposerActions {
  update: (updater: (state: ComposerState) => ComposerState) => void
  submit: () => void
}

interface ComposerMeta {
  inputRef: React.RefObject<TextInput>
}

interface ComposerContextValue {
  state: ComposerState
  actions: ComposerActions
  meta: ComposerMeta
}

const ComposerContext = createContext<ComposerContextValue | null>(null)

UI components consume the interface, not the implementation:

function ComposerInput() {
  const {
    state,
    actions: { update },
    meta,
  } = use(ComposerContext)

  // This component works with ANY provider that implements the interface
  return (
    <TextInput
      ref={meta.inputRef}
      value={state.input}
      onChangeText={(text) => update((s) => ({ ...s, input: text }))}
    />
  )
}

Different providers implement the same interface:

// Provider A: Local state for ephemeral forms
function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
  const [state, setState] = useState(initialState)
  const inputRef = useRef(null)
  const submit = useForwardMessage()

  return (
    <ComposerContext
      value={{
        state,
        actions: { update: setState, submit },
        meta: { inputRef },
      }}
    >
      {children}
    </ComposerContext>
  )
}

// Provider B: Global synced state for channels
function ChannelProvider({ channelId, children }: Props) {
  const { state, update, submit } = useGlobalChannel(channelId)
  const inputRef = useRef(null)

  return (
    <ComposerContext
      value={{
        state,
        actions: { update, submit },
        meta: { inputRef },
      }}
    >
      {children}
    </ComposerContext>
  )
}

The same composed UI works with both:

// Works with ForwardMessageProvider (local state)
<ForwardMessageProvider>
  <Composer.Frame>
    <Composer.Input />
    <Composer.Submit />
  </Composer.Frame>
</ForwardMessageProvider>

// Works with ChannelProvider (global synced state)
<ChannelProvider channelId="abc">
  <Composer.Frame>
    <Composer.Input />
    <Composer.Submit />
  </Composer.Frame>
</ChannelProvider>

Custom UI outside the component can access state and actions:

The provider boundary is what matters—not the visual nesting. Components that need shared state don't have to be inside the Composer.Frame. They just need to be within the provider.

function ForwardMessageDialog() {
  return (
    <ForwardMessageProvider>
      <Dialog>
        {/* The composer UI */}
        <Composer.Frame>
          <Composer.Input placeholder="Add a message, if you'd like." />
          <Composer.Footer>
            <Composer.Formatting />
            <Composer.Emojis />
          </Composer.Footer>
        </Composer.Frame>

        {/* Custom UI OUTSIDE the composer, but INSIDE the provider */}
        <MessagePreview />

        {/* Actions at the bottom of the dialog */}
        <DialogActions>
          <CancelButton />
          <ForwardButton />
        </DialogActions>
      </Dialog>
    </ForwardMessageProvider>
  )
}

// This button lives OUTSIDE Composer.Frame but can still submit based on its context!
function ForwardButton() {
  const {
    actions: { submit },
  } = use(ComposerContext)
  return <Button onPress={submit}>Forward</Button>
}

// This preview lives OUTSIDE Composer.Frame but can read composer's state!
function MessagePreview() {
  const { state } = use(ComposerContext)
  return <Preview message={state.input} attachments={state.attachments} />
}

The ForwardButton and MessagePreview are not visually inside the composer box, but they can still access its state and actions. This is the power of lifting state into providers.

The UI is reusable bits you compose together. The state is dependency-injected by the provider. Swap the provider, keep the UI.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
vercel
Publisher
Vercel (Official)
Source
vercel-labs/agent-skills · skills/composition-patterns · commit 1a2c79d
Licence
MIT License (redistribution allowed)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by vercel or Vercel.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download vercel-composition-patterns.zip