Reactreactpatternscompound-componentscompositionproduction-ready

Compound Components Pattern

A React pattern for building flexible, implicitly shared-state component APIs like Tabs, Accordion, and Select using context.

import { createContext, useContext, useState, useCallback, Children, ReactNode } from "react";

// Accordion compound component
interface AccordionContextValue {
  openItems: Set<string>;
  toggle: (id: string) => void;
  multiple: boolean;
}

const AccordionContext = createContext<AccordionContextValue | null>(null);

function useAccordionContext() {
  const context = useContext(AccordionContext);
  if (!context) {
    throw new Error("Accordion components must be used within an Accordion");
  }
  return context;
}

interface AccordionProps {
  children: ReactNode;
  multiple?: boolean;
  defaultOpen?: string[];
  onChange?: (openItems: string[]) => void;
}

export function Accordion({ children, multiple = false, defaultOpen = [], onChange }: AccordionProps) {
  const [openItems, setOpenItems] = useState<Set<string>>(new Set(defaultOpen));

  const toggle = useCallback((id: string) => {
    setOpenItems((prev) => {
      const next = new Set(prev);
      if (next.has(id)) {
        next.delete(id);
      } else {
        if (!multiple) next.clear();
        next.add(id);
      }
      onChange?.([...next]);
      return next;
    });
  }, [multiple, onChange]);

  return (
    <AccordionContext.Provider value={{ openItems, toggle, multiple }}>
      <div role="region">{children}</div>
    </AccordionContext.Provider>
  );
}

interface AccordionItemProps {
  id: string;
  children: ReactNode;
}

function AccordionItem({ id, children }: AccordionItemProps) {
  const { openItems } = useAccordionContext();
  const isOpen = openItems.has(id);

  return (
    <div data-state={isOpen ? "open" : "closed"}>
      {children}
    </div>
  );
}

interface AccordionTriggerProps {
  id: string;
  children: ReactNode;
  className?: string;
}

function AccordionTrigger({ id, children, className }: AccordionTriggerProps) {
  const { openItems, toggle } = useAccordionContext();
  const isOpen = openItems.has(id);

  return (
    <button
      className={className}
      onClick={() => toggle(id)}
      aria-expanded={isOpen}
      aria-controls={`accordion-content-${id}`}
    >
      {children}
    </button>
  );
}

interface AccordionContentProps {
  id: string;
  children: ReactNode;
  className?: string;
}

function AccordionContent({ id, children, className }: AccordionContentProps) {
  const { openItems } = useAccordionContext();
  const isOpen = openItems.has(id);

  if (!isOpen) return null;

  return (
    <div
      id={`accordion-content-${id}`}
      role="region"
      className={className}
    >
      {children}
    </div>
  );
}

// Attach sub-components
Accordion.Item = AccordionItem;
Accordion.Trigger = AccordionTrigger;
Accordion.Content = AccordionContent;

title: "Compound Components Pattern" description: "A React pattern for building flexible, implicitly shared-state component APIs like Tabs, Accordion, and Select using context." category: "React" language: "typescript" tags: ["react", "patterns", "compound-components", "composition", "production-ready"] createdAt: "2025-02-12" updatedAt: "2025-03-01"

Overview

The compound component pattern provides a declarative, flexible API where parent and child components share implicit state through React context. This enables consumers to compose components freely while the parent manages coordination logic internally.

Code

<Accordion multiple>
  <Accordion.Item id="1">
    <Accordion.Trigger id="1">Title</Accordion.Trigger>
    <Accordion.Content id="1">Content</Accordion.Content>
  </Accordion.Item>
</Accordion>

Notes

  • Context ensures sub-components throw helpful errors when used outside their parent
  • The multiple prop controls whether multiple items can be open simultaneously
  • ARIA attributes (aria-expanded, aria-controls, role) ensure accessibility
  • Attach sub-components as static properties for a clean dot-notation API
  • This pattern is used by Radix UI, Headless UI, and Reach UI