React Component Patterns

React Component Patterns

When to Use

Use this skill when:

• A user asks how to structure React components -- choosing between presentational vs. container, compound components, render props, hooks-based composition, or higher-order components
• A user is refactoring a component that has grown beyond ~200 lines and needs to be decomposed into a maintainable pattern
• A user wants to share logic across components without duplicating state management or side-effect code
• A user is building a design system or component library and needs patterns that scale across a team of 2 to 50+ engineers
• A user has a specific React problem such as prop drilling deeper than 2-3 levels, a component with more than 5 props that are conditionally used, or a component that needs to support multiple UI variants
• A user is migrating class components to functional components and needs to understand the equivalent patterns
• A user asks about TypeScript generics in React components, discriminated union props, or typed context
• A user is implementing features like modals, forms, data tables, or wizard flows that have well-established component pattern solutions

Do NOT use this skill when:

• The user needs state management architecture beyond component scope -- refer to a Redux, Zustand, or Jotai skill instead
• The user's question is about React performance optimization at the rendering level (memoization strategies, profiling, virtualization) -- those are distinct concerns
• The user needs Next.js or Remix routing patterns, server components, or SSR architecture -- refer to the framework-specific skill
• The user is asking about CSS-in-JS, styling architecture, or Tailwind integration -- refer to the styling skill
• The user needs testing patterns for React components -- refer to the React Testing Library or Jest skill
• The user is building in a non-React framework (Vue, Svelte, Angular) -- the patterns have analogs but the implementation differs enough to require separate guidance
• The user only needs a single simple component with no composition requirements -- skip the pattern discussion and just write the component

Process

1. Diagnose the composition problem

Before recommending any pattern, identify the specific structural problem:

• Props explosion: Does the component accept more than 5 props, with some props only relevant under certain conditions? This signals a need for compound components or discriminated union props.
• Logic duplication: Is the same stateful logic (e.g., toggle, pagination, async fetch) copy-pasted across 2 or more components? This signals a custom hook extraction.
• Render flexibility: Does the parent need control over what gets rendered inside a child? This signals render props or the children composition pattern.
• Behavior without UI: Does the logic need to be reusable without being tied to specific markup? This signals a headless component or custom hook.
• Cross-cutting concerns: Does authentication, logging, error boundary, or feature-flag logic need to wrap many unrelated components? This signals a higher-order component (HOC) or a context-aware wrapper.
• Sibling communication: Are sibling components fighting over shared state via a common ancestor? This signals context with a provider, or a colocation refactor.
• Count real prop usage -- if 3 of 8 props are only used for one variant, the component is doing too much and needs splitting.

2. Select the right pattern using the decision tree

Apply this decision logic in order:

• Is the component purely presentational with no internal state or effects? -- Use a simple functional component with typed props. No pattern overhead needed.
• Is there stateful logic that multiple components need? -- Extract a custom hook. This is almost always the right first move before reaching for any other pattern.
• Does the parent need to control the internal rendering structure (e.g., a Tab component where the parent composes Tab.Panel, Tab.Header)? -- Use the compound component pattern with context.
• Does the consumer need full control over what gets rendered for a specific slot while you control behavior? -- Use render props or function-as-child. This is most appropriate for headless utilities like drag-and-drop, virtualized lists, or animation wrappers.
• Do you need to inject behavior into a component you cannot modify (third-party or legacy)? -- Use a higher-order component (HOC). Keep HOCs thin; they should inject at most 1-3 props.
• Do you need a flexible layout with named regions (header, sidebar, content, footer)? -- Use the slot pattern via explicitly named children props (e.g., headerSlot, footerSlot) or React's Children.toArray with element type checking.
• Are you building a controlled form field or complex input? -- Use the controlled component pattern with explicit value and onChange props, and expose a defaultValue for uncontrolled usage.
• Does a deeply nested component need access to configuration or theme? -- Use React Context with a typed provider. Never use context for high-frequency updates (more than a few times per second) -- reach for Zustand or Jotai instead.

3. Define the component's contract with TypeScript

A well-typed component API prevents misuse better than documentation:

• Use discriminated union props for variant behavior: type ButtonProps = { variant: 'primary'; onClick: () => void } | { variant: 'link'; href: string }. This eliminates impossible prop combinations at compile time.
• Use React.ComponentPropsWithoutRef<'button'> or React.HTMLAttributes<HTMLDivElement> to extend native element props and pass through className, style, aria-*, and event handlers automatically.
• Use generic components for data-driven patterns: function List<T extends { id: string }>({ items, renderItem }: ListProps<T>). This gives consumers type inference without casting.
• Mark props as readonly arrays to prevent mutation bugs.
• Use React.ReactNode for children, not JSX.Element -- ReactNode accepts strings, arrays, null, and fragments.
• Export both the component and its props type: export type { ButtonProps }. Library consumers need this.
• Use forwardRef with the correct generic signature when building input components or any component that wraps a DOM element: React.forwardRef<HTMLButtonElement, ButtonProps>.

4. Implement the pattern with production conventions

Follow these conventions for each major pattern:

Custom Hook:

• Name starts with use, returns a stable object (wrap with useMemo if the object identity matters to consumers).
• Accept an optional options parameter for configuration rather than multiple positional arguments.
• Handle cleanup in useEffect return -- never leave subscriptions, timers, or event listeners open.
• Example structure: const { data, isLoading, error, refetch } = useAsyncData(fetchFn, options).

Compound Component:

• Create a private Context to pass internal state between parent and children.
• Attach child components as static properties: Tabs.Panel, Tabs.Header, Tabs.Trigger.
• Add displayName to all sub-components for React DevTools readability.
• Guard against consumer misuse: throw a descriptive error if a child component is used outside its parent context.

Render Props / Function as Child:

• The render function receives a typed bag of state and handlers: children: (state: { isOpen: boolean; toggle: () => void }) => ReactNode.
• Memoize the state bag or individual functions to avoid unnecessary re-renders in consumers.
• Document the shape of the state bag in the TypeScript interface, not in comments.

Higher-Order Component:

• Name the HOC withX (e.g., withAuth, withErrorBoundary).
• Always forward refs using React.forwardRef inside the HOC.
• Copy static properties from the wrapped component using hoistNonReactStatics from the hoist-non-react-statics package.
• Set WrappedComponent.displayName to withX(ComponentName).
• Prefer HOCs only for cross-cutting concerns; prefer hooks for logic reuse.

Controlled / Uncontrolled Input:

• Support both modes: check if (value !== undefined) to detect controlled mode.
• In controlled mode, call onChange synchronously on every user interaction.
• In uncontrolled mode, use useRef to expose a getValue() imperative API via forwardRef and useImperativeHandle.

5. Handle state colocation and context boundaries

• Colocate state as close to where it is used as possible. Avoid lifting state to the top of a component tree before profiling shows it is necessary.
• A Context provider should own exactly one concern (e.g., ThemeContext, AuthContext, ToastContext). Never put unrelated state into a single context object.
• Memoize context values: const value = useMemo(() => ({ user, logout }), [user]). Without this, every consumer re-renders on every parent render.
• For components that read context but render frequently, split the context into a state context and a dispatch context to minimize re-renders. Pattern: UserStateContext and UserDispatchContext as two separate providers.
• Avoid context for ephemeral, high-frequency values like scroll position, mouse coordinates, or animation frame data -- use refs or event listeners instead.

6. Structure the file and module layout

• One component per file for anything beyond trivial sub-components. The file name matches the component name: UserCard.tsx, not components.tsx.
• Folder structure for a component with multiple pieces:

  UserCard/
    index.ts          -- re-exports the public API
    UserCard.tsx      -- main component
    UserCard.types.ts -- exported TypeScript interfaces
    UserCard.test.tsx -- co-located tests
    useUserCard.ts    -- extracted hook (if stateful logic is substantial)
  

• Export the component as a named export, not default export. Named exports are refactor-safe and tree-shakeable.
• The index.ts barrel file should only re-export what is public API: export { UserCard } from './UserCard' and export type { UserCardProps } from './UserCard.types'.

7. Validate the pattern choice with these checkpoints

Before finalizing, verify:

• Can a new team member understand the component's responsibility in under 60 seconds? If not, it is still too complex.
• Does the component have a single reason to change? If changing the data source AND changing the visual layout both require edits to the same component, it needs further decomposition.
• Are there more than 2 levels of nesting in the JSX returned by the component? Flatten using sub-components.
• Does every prop on the component's interface have a consumer that actually uses it? Unused prop surface is dead weight.
• Is the component testable in isolation without mocking the entire application? If not, the dependencies are too tightly coupled.

8. Document the pattern decision

For each non-obvious pattern choice, add a brief comment block at the top of the file:

/**
 * Pattern: Compound Component
 * Reason: Consumers need to control the order and presence of Tab panels
 *         without forking this component. The compound pattern gives layout
 *         flexibility while keeping tab state internal.
 * Trade-off: More verbose consumer API than a prop-driven tab component,
 *            but eliminates the need for index-based panel management.
 */

Output Format

When responding to a user about React component patterns, structure the output as follows:

## Pattern Diagnosis

**Problem identified:** [One sentence describing the structural issue]
**Pattern selected:** [Pattern name]
**Rationale:** [2-3 sentences explaining why this pattern fits better than alternatives]

## Decision Matrix

| Criteria                  | Compound Component | Render Props | Custom Hook | HOC   |
|---------------------------|-------------------|--------------|-------------|-------|
| Logic reuse               | Partial           | No           | Yes         | Yes   |
| Render flexibility        | Yes               | Yes          | No          | No    |
| TypeScript ergonomics     | Good              | Moderate     | Excellent   | Poor  |
| Debuggability             | Good              | Moderate     | Excellent   | Poor  |
| Boilerplate overhead      | High              | Low          | Low         | High  |
| Best for                  | UI composition    | Headless UI  | Logic reuse | X-cutting |

**Recommended for this case:** [Selected pattern with one-line justification]

## Implementation

### Types (UserCard.types.ts)
[Complete TypeScript interface definitions]

### Hook (useX.ts -- if applicable)
[Complete custom hook implementation]

### Component (ComponentName.tsx)
[Complete component implementation]

### Usage Example
[How a consumer would use this component in practice]

## Trade-offs and Limitations

- **What this pattern does well:** [Specific strengths in this context]
- **What to watch for:** [Specific failure modes or complexity traps]
- **When to change patterns:** [Concrete signals that this pattern has been outgrown]

Rules

1. NEVER recommend HOCs as the first solution for logic reuse. Custom hooks replaced HOCs for logic extraction in React 16.8+. HOCs should only be recommended when wrapping a component you cannot modify, or when you need to intercept the render lifecycle (e.g., error boundaries, which cannot be hooks).

2. NEVER use React.FC (or React.FunctionComponent) as the component type annotation. React.FC implicitly includes children in props (pre-React 18 behavior), is incompatible with forwardRef signatures, and adds no value over plain function declarations. Always type the function directly: function Button(props: ButtonProps): JSX.Element.

3. NEVER put multiple unrelated stateful concerns into one custom hook. A hook named useUserDashboard that manages authentication, pagination, and modal state is a monolith in hook form. Each hook should own exactly one concern.

4. NEVER use Children.map or Children.toArray to enumerate children for logic purposes. This pattern breaks with React fragments, portals, and arrays. Use Context to share state between a parent and its compound children instead.

5. ALWAYS memoize context values that are objects or arrays: useMemo(() => ({ theme, setTheme }), [theme]). Failing to do this causes all context consumers to re-render on every provider parent render, regardless of whether the consumed values changed.

6. NEVER use index as the key prop for lists that can be reordered, filtered, or paginated. Keys must be stable, unique identifiers tied to the data item (item.id). Index keys cause incorrect reconciliation behavior and subtle UI bugs with controlled inputs inside list items.

7. ALWAYS use forwardRef when building any component that wraps a DOM input, button, or other focusable element. Library consumers and accessibility tools (screen reader management, focus trapping) depend on the ability to imperatively focus these elements.

8. NEVER lift state above the lowest common ancestor that actually needs it. Premature state lifting creates unnecessary re-render surfaces. Profile first with React DevTools Profiler before deciding to lift state.

9. ALWAYS discriminate between controlled and uncontrolled usage for any component that holds user input state. A component that accepts a value prop must not also maintain internal state -- it must be fully controlled. Mixing modes creates the React "uncontrolled to controlled" warning and unpredictable behavior.

10. NEVER export components as default exports in a library or design system. Default exports lose their name during tree-shaking analysis, break automated refactoring tools, and create inconsistency when re-exported from barrel files. Named exports are the correct convention for shared component libraries.

Edge Cases

Legacy class component coexistence

When introducing functional component patterns into a codebase that still has class components, render props created with class components remain compatible with functional component consumers. Custom hooks, however, cannot be called inside class components. If a hook-based pattern needs to be consumed by an existing class component, create a thin adapter HOC: wrap the functional hook component in a class-compatible HOC that passes hook results as props. Mark the adapter as @deprecated so the team knows it is a migration shim, not a permanent pattern.

Compound component with deeply nested consumers

The standard compound component pattern passes context from the immediate parent to direct children. If a consumer places a non-compound component several levels deep inside the compound root (e.g., <Tabs><CustomWrapper><Tabs.Panel /></CustomWrapper></Tabs>), the context still flows correctly because React Context is not limited to direct children. However, if a consumer forgets to render children inside the compound root entirely and uses Tabs.Panel standalone, it will receive undefined context. Guard against this by checking context value in each sub-component: if (!context) throw new Error('Tabs.Panel must be used inside a Tabs component').

Generic components and TypeScript inference failures

Generic components (function List<T>) lose their type parameter when used with React.memo or forwardRef because these wrappers do not propagate generics. Work around this with one of two approaches: (1) cast the result with an explicit generic signature after wrapping -- const MemoList = React.memo(List) as typeof List -- or (2) use a non-generic overload signature on the export. The as typeof List cast is the most pragmatic approach and preserves the generic call signature for all consumers.

Render prop performance with frequent re-renders

Render props defined inline in JSX recreate a new function reference on every parent render: <Toggle>{({ isOn }) => <Button active={isOn} />}</Toggle>. If the Toggle component uses React.PureComponent or React.memo, the inline function will defeat memoization because the function reference always changes. Solutions: (1) define the render prop function outside the render method or use useCallback, (2) avoid memoizing the Toggle component itself since it is always expected to re-render with its parent, or (3) switch to the compound component pattern if the consumer structure allows it.

Context performance with high consumer count

A single Context with 50+ consumers and a state that changes frequently (e.g., a real-time data feed) will cause severe performance problems because every consumer re-renders on every update, even if the specific slice they consume did not change. Solutions in order of preference: (1) split the context into multiple fine-grained contexts, (2) use context selectors via use-context-selector library which enables subscribing to derived slices, (3) move the high-frequency state out of React context entirely and into a pub/sub system (Zustand, Jotai, or a plain EventEmitter with refs).

Component with polymorphic as prop

A polymorphic component (e.g., <Button as="a" href="/home">) must be typed so that TypeScript infers the correct prop set for the underlying element. This requires a generic constraint: type PolymorphicProps<E extends React.ElementType> = { as?: E } & React.ComponentPropsWithoutRef<E>. Without this, passing href to a <Button as="a"> will produce a TypeScript error, and passing invalid props for the rendered element will not be caught. The complexity of this typing is significant -- if the team is not comfortable with the generic constraints, prefer explicit variant props (variant="link" renders an anchor internally) over the polymorphic pattern.

Islands of interactivity in server-rendered applications

In Next.js App Router or Remix, React Server Components cannot use hooks, context, or event handlers. When a component pattern relies on hooks (custom hook pattern, compound components with context), the component must be marked 'use client'. Compound component parents that establish context must be client components even if the children contain server-renderable content. The correct split: mark the context provider as 'use client', and let children that need no interactivity remain server components -- React will hydrate only the client boundary, not the children.

Stale closure bugs in custom hooks

A custom hook that captures a callback in a useEffect without including it in the dependency array will produce stale closures -- the callback sees the variable values from when the effect was created, not the current values. Always use useCallback to stabilize callback props before including them in effect dependencies, or use the useEffectEvent pattern (React 19+, or the userland equivalent via a ref: store the latest callback in a ref and call the ref inside the effect).

Example

Input: "I'm building a multi-step form wizard in React with TypeScript. The wizard has 5 steps. Different parts of the UI need to know the current step, and I need to be able to navigate forward, backward, and jump to a specific step. I also need to validate each step before allowing progression. I have this all tangled up in one 400-line component and need to break it out properly."

Output:

Pattern Diagnosis

Problem identified: A monolithic form wizard component with mixed concerns -- step state management, navigation logic, per-step validation, and rendering of multiple step views -- crammed into a single component.

Pattern selected: Compound Component (for the wizard shell and step layout) + Custom Hook (for step state and navigation logic) + Discriminated Union Props (for per-step data typing).

Rationale: The compound component pattern gives consumers control over which steps appear and in what order without requiring index-based configuration. The custom hook extracts all navigation and validation logic into a testable, reusable unit. The discriminated union ensures each step receives exactly the props it needs with no impossible combinations.

Decision Matrix

Recommended for this case: Compound Component + Custom Hook -- the wizard needs both render flexibility (consumers compose steps) and shared state (current step, validation) accessible to navigation controls and step indicators simultaneously.

Implementation

Types -- Wizard.types.ts

export type StepStatus = 'incomplete' | 'active' | 'complete' | 'error';

export interface StepConfig {
  id: string;
  label: string;
  validate?: (data: unknown) => Promise<string[]> | string[];
}

export interface WizardContextValue {
  currentStepIndex: number;
  steps: StepConfig[];
  stepStatuses: Record<string, StepStatus>;
  validationErrors: Record<string, string[]>;
  goToNext: () => Promise<boolean>;
  goToPrev: () => void;
  goToStep: (index: number) => void;
  registerStep: (config: StepConfig) => void;
}

export interface WizardProps {
  children: React.ReactNode;
  onComplete: (data: Record<string, unknown>) => void;
  initialData?: Record<string, unknown>;
}

export interface WizardStepProps {
  stepId: string;
  children: React.ReactNode;
  validate?: StepConfig['validate'];
}

export interface WizardNavigationProps {
  nextLabel?: string;
  prevLabel?: string;
  completeLabel?: string;
}

Custom Hook -- useWizard.ts

import { useCallback, useMemo, useRef, useState } from 'react';
import type { StepConfig, StepStatus, WizardContextValue } from './Wizard.types';

export function useWizard(): WizardContextValue {
  const [currentStepIndex, setCurrentStepIndex] = useState(0);
  const [stepStatuses, setStepStatuses] = useState<Record<string, StepStatus>>({});
  const [validationErrors, setValidationErrors] = useState<Record<string, string[]>>({});
  const stepsRef = useRef<StepConfig[]>([]);

  const registerStep = useCallback((config: StepConfig) => {
    // Prevent duplicate registration on re-renders
    if (stepsRef.current.some((s) => s.id === config.id)) return;
    stepsRef.current = [...stepsRef.current, config];
    setStepStatuses((prev) => ({ ...prev, [config.id]: 'incomplete' }));
  }, []);

  const goToNext = useCallback(async (): Promise<boolean> => {
    const currentStep = stepsRef.current[currentStepIndex];
    if (!currentStep) return false;

    if (currentStep.validate) {
      const errors = await currentStep.validate({});
      if (errors.length > 0) {
        setValidationErrors((prev) => ({ ...prev, [currentStep.id]: errors }));
        setStepStatuses((prev) => ({ ...prev, [currentStep.id]: 'error' }));
        return false;
      }
    }

    setValidationErrors((prev) => ({ ...prev, [currentStep.id]: [] }));
    setStepStatuses((prev) => ({ ...prev, [currentStep.id]: 'complete' }));

    setCurrentStepIndex((i) => {
      const nextIndex = Math.min(i + 1, stepsRef.current.length - 1);
      const nextStep = stepsRef.current[nextIndex];
      if (nextStep && nextIndex !== i) {
        setStepStatuses((s) => ({ ...s, [nextStep.id]: 'active' }));
      }
      return nextIndex;
    });

    return true;
  }, [currentStepIndex]);

  const goToPrev = useCallback(() => {
    setCurrentStepIndex((i) => {
      const prevIndex = Math.max(i - 1, 0);
      const prevStep = stepsRef.current[prevIndex];
      if (prevStep) {
        setStepStatuses((s) => ({ ...s, [prevStep.id]: 'active' }));
      }
      return prevIndex;
    });
  }, []);

  const goToStep = useCallback((index: number) => {
    if (index < 0 || index >= stepsRef.current.length) return;
    setCurrentStepIndex(index);
    const step = stepsRef.current[index];
    if (step) {
      setStepStatuses((s) => ({ ...s, [step.id]: 'active' }));
    }
  }, []);

  const value = useMemo(
    () => ({
      currentStepIndex,
      steps: stepsRef.current,
      stepStatuses,
      validationErrors,
      goToNext,
      goToPrev,
      goToStep,
      registerStep,
    }),
    [currentStepIndex, stepStatuses, validationErrors, goToNext, goToPrev, goToStep, registerStep]
  );

  return value;
}

Context -- WizardContext.ts

import { createContext, useContext } from 'react';
import type { WizardContextValue } from './Wizard.types';

export const WizardContext = createContext<WizardContextValue | null>(null);
WizardContext.displayName = 'WizardContext';

export function useWizardContext(): WizardContextValue {
  const ctx = useContext(WizardContext);
  if (!ctx) {
    throw new Error(
      'useWizardContext must be used inside a <Wizard> component. ' +
      'Ensure Wizard.Step and Wizard.Navigation are rendered as children of Wizard.'
    );
  }
  return ctx;
}

Compound Component -- Wizard.tsx

/**
 * Pattern: Compound Component + Custom Hook
 * Reason: The wizard needs to share navigation state (current step, validation errors)
 *         between a progress indicator, step content panels, and navigation buttons
 *         without threading props through multiple layers.
 * Trade-off: Consumers must render Wizard.Step and Wizard.Navigation inside Wizard.
 *            Standalone usage of sub-components outside Wizard throws a descriptive error.
 */
import React, { useEffect } from 'react';
import { WizardContext, useWizardContext } from './WizardContext';
import { useWizard } from './useWizard';
import type { WizardNavigationProps, WizardProps, WizardStepProps } from './Wizard.types';

function WizardRoot({ children, onComplete }: WizardProps): JSX.Element {
  const wizard = useWizard();

  return (
    <WizardContext.Provider value={wizard}>
      <div role="group" aria-label="Multi-step form wizard">
        {children}
      </div>
    </WizardContext.Provider>
  );
}

WizardRoot.displayName = 'Wizard';

function WizardStep({ stepId, children, validate }: WizardStepProps): JSX.Element | null {
  const { currentStepIndex, steps, registerStep, validationErrors } = useWizardContext();

  useEffect(() => {
    registerStep({ id: stepId, label: stepId, validate });
    // registerStep is stable (useCallback with no deps that change)
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [stepId]);

  const stepIndex = steps.findIndex((s) => s.id === stepId);
  const isActive = stepIndex === currentStepIndex;

  if (!isActive) return null;

  const errors = validationErrors[stepId] ?? [];

  return (
    <div
      role="tabpanel"
      aria-labelledby={`wizard-step-${stepId}`}
      id={`wizard-panel-${stepId}`}
    >
      {errors.length > 0 && (
        <ul role="alert" aria-live="polite">
          {errors.map((error) => (
            <li key={error} style={{ color: 'red' }}>
              {error}
            </li>
          ))}
        </ul>
      )}
      {children}
    </div>
  );
}

WizardStep.displayName = 'Wizard.Step';

function WizardNavigation({
  nextLabel = 'Next',
  prevLabel = 'Back',
  completeLabel = 'Submit',
}: WizardNavigationProps): JSX.Element {
  const { currentStepIndex, steps, goToNext, goToPrev } = useWizardContext();

  const isFirstStep = currentStepIndex === 0;
  const isLastStep = currentStepIndex === steps.length - 1;

  return (
    <nav aria-label="Wizard navigation">
      <button
        type="button"
       
        disabled={isFirstStep}
        aria-disabled={isFirstStep}
      >
        {prevLabel}
      </button>
      <button
        type="button"
        => void goToNext()}
      >
        {isLastStep ? completeLabel : nextLabel}
      </button>
    </nav>
  );
}

WizardNavigation.displayName = 'Wizard.Navigation';

function WizardProgress(): JSX.Element {
  const { steps, currentStepIndex, stepStatuses, goToStep } = useWizardContext();

  return (
    <ol aria-label="Form progress" role="list">
      {steps.map((step, index) => (
        <li key={step.id} aria-current={index === currentStepIndex ? 'step' : undefined}>
          <button
            type="button"
            => goToStep(index)}
            aria-label={`Go to step ${index + 1}: ${step.label}`}
            data-status={stepStatuses[step.id] ?? 'incomplete'}
          >
            {index + 1}. {step.label}
          </button>
        </li>
      ))}
    </ol>
  );
}

WizardProgress.displayName = 'Wizard.Progress';

export const Wizard = Object.assign(WizardRoot, {
  Step: WizardStep,
  Navigation: WizardNavigation,
  Progress: WizardProgress,
});

Public API -- index.ts

export { Wizard } from './Wizard';
export { useWizardContext } from './WizardContext';
export type {
  WizardProps,
  WizardStepProps,
  WizardNavigationProps,
  StepConfig,
  StepStatus,
} from './Wizard.types';

Consumer Usage Example

import { Wizard } from '@/components/Wizard';

async function validatePersonalInfo(data: unknown): Promise<string[]> {
  const errors: string[] = [];
  // Real validation logic here
  return errors;
}

export function OnboardingWizard(): JSX.Element {
  function handleComplete(data: Record<string, unknown>) {
    console.log('Wizard complete', data);
  }

  return (
    <Wizard
      <Wizard.Progress />

      <Wizard.Step stepId="personal-info" validate={validatePersonalInfo}>
        <h2>Personal Information</h2>
        <input type="text" placeholder="First name" aria-label="First name" />
        <input type="text" placeholder="Last name" aria-label="Last name" />
      </Wizard.Step>

      <Wizard.Step stepId="contact-details">
        <h2>Contact Details</h2>
        <input type="email" placeholder="Email address" aria-label="Email address" />
      </Wizard.Step>

      <Wizard.Step stepId="preferences">
        <h2>Preferences</h2>
        <label>
          <input type="checkbox" />
          Receive email notifications
        </label>
      </Wizard.Step>

      <Wizard.Navigation
        nextLabel="Continue"
        prevLabel="Go Back"
        completeLabel="Create Account"
      />
    </Wizard>
  );
}

Trade-offs and Limitations

• What this pattern does well: Navigation state is centralized in one hook and shared via context -- no prop drilling through 5 step components. The compound API gives consumers complete control over step content and order. Validation is co-located with step configuration. Adding a 6th step requires zero changes to the Wizard component itself.

• What to watch for: The registerStep pattern using a ref and effect can have ordering issues if steps are conditionally rendered -- a step that mounts late will append to the steps array in registration order, not DOM order. If conditional steps are a requirement, switch to a declarative steps array passed directly to the Wizard root prop instead of relying on registration side effects.

• When to change patterns: If the wizard needs to persist state across browser sessions (resumable forms), extract the state from useWizard into a useReducer + localStorage synchronization layer. If more than 3 components outside the Wizard tree need to read the current step (e.g., a page-level breadcrumb), promote the context to a higher level or move to a global state manager like Zustand.