Compound Components Pattern in React

// ❌ Rigid API — layout locked, props explode
<Modal
  isOpen={open}
  onClose={close}
  title="Delete account"
  showFooter
  footerAlign="right"
  primaryLabel="Delete"
  secondaryLabel="Cancel"
  onPrimary={handleDelete}
  onSecondary={close}
  hideCloseButton={false}
  size="md"
  body={<p>This cannot be undone.</p>}
/>

<Tabs>           ← container: owns active index
  <Tabs.List>    ← layout region
    <Tabs.Tab /> ← dumb: reads context, fires setActive
  </Tabs.List>
  <Tabs.Panel /> ← dumb: shows/hides based on context
</Tabs>

'use client'
 
import { createContext, useContext, useMemo, useState, type ReactNode } from 'react'
 
// 1. Context + hook with guard
type ToggleContextValue = {
  open: boolean
  toggle: () => void
}
 
const ToggleContext = createContext<ToggleContextValue | null>(null)
 
function useToggle() {
  const ctx = useContext(ToggleContext)
  if (!ctx) throw new Error('Toggle sub-components must be used within <Toggle>')
  return ctx
}
 
// 2. Parent container
function Toggle({ defaultOpen = false, children }: { defaultOpen?: boolean; children: ReactNode }) {
  const [open, setOpen] = useState(defaultOpen)
 
  const value = useMemo(() => ({ open, toggle: () => setOpen((o) => !o) }), [open])
 
  return <ToggleContext.Provider value={value}>{children}</ToggleContext.Provider>
}
 
// 3. Dumb sub-components
function ToggleButton({ children }: { children: ReactNode }) {
  const { toggle, open } = useToggle()
  return (
    <button type="button" aria-expanded={open} onClick={toggle}>
      {children}
    </button>
  )
}
 
function TogglePanel({ children }: { children: ReactNode }) {
  const { open } = useToggle()
  if (!open) return null
  return <div role="region">{children}</div>
}
 
// 4. Dot notation + 5. single export
Toggle.Button = ToggleButton
Toggle.Panel = TogglePanel
 
export { Toggle }

'use client'
 
import { createContext, useCallback, useContext, useEffect, useMemo, useState, type ReactNode } from 'react'
 
type ModalContextValue = {
  open: boolean
  onClose: () => void
}
 
const ModalContext = createContext<ModalContextValue | null>(null)
 
function useModal() {
  const ctx = useContext(ModalContext)
  if (!ctx) throw new Error('Modal.* must be used within <Modal>')
  return ctx
}
 
type ModalProps = {
  open: boolean
  onClose: () => void
  children: ReactNode
}
 
function Modal({ open, onClose, children }: ModalProps) {
  const value = useMemo(() => ({ open, onClose }), [open, onClose])
 
  useEffect(() => {
    if (!open) return
    function onKey(e: KeyboardEvent) {
      if (e.key === 'Escape') onClose()
    }
    window.addEventListener('keydown', onKey)
    return () => window.removeEventListener('keydown', onKey)
  }, [open, onClose])
 
  if (!open) return null
 
  return (
    <ModalContext.Provider value={value}>
      <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50" role="dialog" aria-modal="true">
        <div className="w-full max-w-md rounded-lg bg-white shadow-xl">{children}</div>
      </div>
    </ModalContext.Provider>
  )
}
 
function ModalHeader({ children }: { children: ReactNode }) {
  const { onClose } = useModal()
  return (
    <header className="flex items-center justify-between border-b px-4 py-3">
      <h2 className="text-lg font-bold">{children}</h2>
      <button type="button" aria-label="Close" onClick={onClose}>
        ×
      </button>
    </header>
  )
}
 
function ModalBody({ children }: { children: ReactNode }) {
  return <div className="px-4 py-4">{children}</div>
}
 
function ModalFooter({ children }: { children: ReactNode }) {
  return <footer className="flex justify-end gap-2 border-t px-4 py-3">{children}</footer>
}
 
Modal.Header = ModalHeader
Modal.Body = ModalBody
Modal.Footer = ModalFooter
 
export { Modal }

'use client'
 
import { useState } from 'react'
import { Modal } from './Modal'
 
export function DeleteAccountDialog() {
  const [open, setOpen] = useState(false)
 
  return (
    <>
      <button type="button" onClick={() => setOpen(true)}>
        Delete account
      </button>
 
      <Modal open={open} onClose={() => setOpen(false)}>
        <Modal.Header>Delete account</Modal.Header>
        <Modal.Body>
          <p>This permanently removes your data.</p>
          <label className="mt-4 flex items-center gap-2">
            <input type="checkbox" />I understand this cannot be undone
          </label>
        </Modal.Body>
        <Modal.Footer>
          <button type="button" onClick={() => setOpen(false)}>
            Cancel
          </button>
          <button type="button" className="bg-red-600 text-white">
            Delete
          </button>
        </Modal.Footer>
      </Modal>
    </>
  )
}

'use client'
 
import { createContext, useContext, useMemo, useState, type ReactNode } from 'react'
 
type AccordionContextValue = {
  openIds: Set<string>
  toggle: (id: string) => void
  allowMultiple: boolean
}
 
const AccordionContext = createContext<AccordionContextValue | null>(null)
 
function useAccordion() {
  const ctx = useContext(AccordionContext)
  if (!ctx) throw new Error('Accordion.Item must be used within <Accordion>')
  return ctx
}
 
type AccordionProps = {
  defaultOpen?: string[]
  allowMultiple?: boolean
  children: ReactNode
}
 
function Accordion({ defaultOpen = [], allowMultiple = false, children }: AccordionProps) {
  const [openIds, setOpenIds] = useState<Set<string>>(() => new Set(defaultOpen))
 
  const toggle = (id: string) => {
    setOpenIds((prev) => {
      const next = new Set(prev)
      if (next.has(id)) {
        next.delete(id)
      } else {
        if (!allowMultiple) next.clear()
        next.add(id)
      }
      return next
    })
  }
 
  const value = useMemo(() => ({ openIds, toggle, allowMultiple }), [openIds, allowMultiple])
 
  return (
    <AccordionContext.Provider value={value}>
      <div className="divide-y rounded border">{children}</div>
    </AccordionContext.Provider>
  )
}
 
type ItemProps = {
  id: string
  title: ReactNode
  children: ReactNode
}
 
function AccordionItem({ id, title, children }: ItemProps) {
  const { openIds, toggle } = useAccordion()
  const expanded = openIds.has(id)
 
  return (
    <div>
      <button
        type="button"
        className="flex w-full items-center justify-between px-4 py-3 text-left font-semibold"
        aria-expanded={expanded}
        onClick={() => toggle(id)}>
        {title}
        <span aria-hidden>{expanded ? '−' : '+'}</span>
      </button>
      {expanded && <div className="px-4 pb-4 text-sm">{children}</div>}
    </div>
  )
}
 
Accordion.Item = AccordionItem
 
export { Accordion }

// Usage
<Accordion defaultOpen={['shipping']} allowMultiple={false}>
  <Accordion.Item id="shipping" title="Shipping policy">
    Free shipping over $50…
  </Accordion.Item>
  <Accordion.Item id="returns" title="Returns">
    30-day return window…
  </Accordion.Item>
</Accordion>

<Menu>
  <Menu.Trigger>Options</Menu.Trigger>
  <Menu.List>
    <Menu.Item onSelect={edit}>Edit</Menu.Item>
    <Menu.Item onSelect={archive}>Archive</Menu.Item>
  </Menu.List>
</Menu>

import type { ReactNode } from 'react'
 
function Card({ children, className = '' }: { children: ReactNode; className?: string }) {
  return <article className={`overflow-hidden rounded-lg border bg-white shadow-sm ${className}`}>{children}</article>
}
 
function CardImage({ src, alt }: { src: string; alt: string }) {
  return <img src={src} alt={alt} className="h-48 w-full object-cover" />
}
 
function CardHeader({ children }: { children: ReactNode }) {
  return <header className="border-b px-4 py-3 font-bold">{children}</header>
}
 
function CardContent({ children }: { children: ReactNode }) {
  return <div className="px-4 py-4 text-sm leading-relaxed">{children}</div>
}
 
function CardFooter({ children }: { children: ReactNode }) {
  return <footer className="flex gap-2 border-t bg-neutral-50 px-4 py-3">{children}</footer>
}
 
Card.Image = CardImage
Card.Header = CardHeader
Card.Content = CardContent
Card.Footer = CardFooter
 
export { Card }

// Product card — image optional, footer optional
<Card>
  <Card.Image src="/headphones.jpg" alt="Headphones" />
  <Card.Header>Wireless Pro X</Card.Header>
  <Card.Content>Noise cancelling, 40h battery, USB-C charging.</Card.Content>
  <Card.Footer>
    <button type="button">Add to cart</button>
    <button type="button">Compare</button>
  </Card.Footer>
</Card>
 
// Blog teaser — no image, no footer
<Card>
  <Card.Header>React 19 Forms</Card.Header>
  <Card.Content>How useActionState changes server forms…</Card.Content>
</Card>

'use client'
 
import { createContext, useContext, useMemo, useState, type ReactNode } from 'react'
 
type TabsContextValue = {
  active: string
  setActive: (id: string) => void
}
 
const TabsContext = createContext<TabsContextValue | null>(null)
 
function useTabs() {
  const ctx = useContext(TabsContext)
  if (!ctx) throw new Error('Tabs.* must be used within <Tabs>')
  return ctx
}
 
function Tabs({
  defaultTab,
  children,
  onChange,
}: {
  defaultTab: string
  children: ReactNode
  onChange?: (id: string) => void
}) {
  const [active, setActiveState] = useState(defaultTab)
 
  const setActive = (id: string) => {
    setActiveState(id)
    onChange?.(id)
  }
 
  const value = useMemo(() => ({ active, setActive }), [active])
 
  return (
    <TabsContext.Provider value={value}>
      <div className="tabs">{children}</div>
    </TabsContext.Provider>
  )
}
 
function TabList({ children }: { children: ReactNode }) {
  return (
    <div role="tablist" className="flex gap-1 border-b">
      {children}
    </div>
  )
}
 
function Tab({ id, children }: { id: string; children: ReactNode }) {
  const { active, setActive } = useTabs()
  const selected = active === id
 
  return (
    <button
      type="button"
      role="tab"
      id={`tab-${id}`}
      aria-selected={selected}
      aria-controls={`panel-${id}`}
      className={selected ? 'border-b-2 border-black font-bold' : ''}
      onClick={() => setActive(id)}>
      {children}
    </button>
  )
}
 
function TabPanel({ id, children }: { id: string; children: ReactNode }) {
  const { active } = useTabs()
  if (active !== id) return null
 
  return (
    <div role="tabpanel" id={`panel-${id}`} aria-labelledby={`tab-${id}`} className="py-4">
      {children}
    </div>
  )
}
 
Tabs.List = TabList
Tabs.Tab = Tab
Tabs.Panel = TabPanel
 
export { Tabs }

// Settings page — reorder List and Panels freely
<Tabs defaultTab="profile" onChange={(id) => analytics.track('tab', id)}>
  <Tabs.List>
    <Tabs.Tab id="profile">Profile</Tabs.Tab>
    <Tabs.Tab id="security">Security</Tabs.Tab>
    <Tabs.Tab id="billing">Billing</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel id="profile">
    <ProfileForm />
  </Tabs.Panel>
  <Tabs.Panel id="security">
    <MfaSettings />
  </Tabs.Panel>
  <Tabs.Panel id="billing">
    <BillingTable />
  </Tabs.Panel>
</Tabs>