Compound Components

Master the Compound Components pattern — a powerful React pattern for building flexible, expressive component APIs. Learn how to build components like Select, Tabs, and Accordion that feel native.

import { createContext, useContext, useState } from 'react';

// Shared state via Context
interface TabsContextValue {
  activeTab: string;
  setActiveTab: (value: string) => void;
}

const TabsContext = createContext<TabsContextValue | null>(null);

const useTabsContext = () => {
  const ctx = useContext(TabsContext);
  if (!ctx) throw new Error('Tabs sub-components must be used within <Tabs>');
  return ctx;
};

// Parent component — owns the state
interface TabsProps {
  children: React.ReactNode;
  defaultValue: string;
  onChange?: (value: string) => void;
}

function Tabs({ children, defaultValue, onChange }: TabsProps) {
  const [activeTab, setActiveTab] = useState(defaultValue);

  const handleChange = (value: string) => {
    setActiveTab(value);
    onChange?.(value);
  };

  return (
    <TabsContext.Provider value={{ activeTab, setActiveTab: handleChange }}>
      <div className="tabs">{children}</div>
    </TabsContext.Provider>
  );
}

// Child components — consume context
function TabList({ children }: { children: React.ReactNode }) {
  return <div className="tabs__list" role="tablist">{children}</div>;
}

function Tab({ value, children }: { value: string; children: React.ReactNode }) {
  const { activeTab, setActiveTab } = useTabsContext();
  const isActive = activeTab === value;

  return (
    <button
      role="tab"
      aria-selected={isActive}
      className={`tabs__tab ${isActive ? 'tabs__tab--active' : ''}`}
      onClick={() => setActiveTab(value)}
    >
      {children}
    </button>
  );
}

function TabPanel({ value, children }: { value: string; children: React.ReactNode }) {
  const { activeTab } = useTabsContext();
  if (activeTab !== value) return null;
  return <div role="tabpanel" className="tabs__panel">{children}</div>;
}

// Attach sub-components as static properties
Tabs.List  = TabList;
Tabs.Tab   = Tab;
Tabs.Panel = TabPanel;

export { Tabs };

// Usage
<Tabs defaultValue="claims" onChange={(tab) => trackTabView(tab)}>
  <Tabs.List>
    <Tabs.Tab value="claims">📋 Claims</Tabs.Tab>
    <Tabs.Tab value="documents">📄 Documents</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="claims"><ClaimsTable /></Tabs.Panel>
  <Tabs.Panel value="documents"><DocumentList /></Tabs.Panel>
</Tabs>

Compound components are the gold standard for design system component APIs. They provide maximum flexibility to consumers while keeping shared state encapsulated. If you are building a component library, every complex interactive component (Tabs, Accordion, Select, Menu, Dialog) should use this pattern. Libraries like Radix UI have proven that compound components with headless (unstyled) implementations are the most reusable foundation for design systems.