Headless UI Primitives & Compound State Contracts
Headless UI primitives separate behavioral state machines from visual markup. Compound subcomponents share an implicit context that wires Accessibility Tree & ARIA attributes, manages Roving Tabindex keyboard navigation, and promotes overlays to the Browser Top Layer.
Compound Primitive ARIA & Focus Contract
Trace how Root, Trigger, and Content coordinate IDs, ARIA state, and focus restoration.
Root generates a stable menuId; Trigger sets aria-expanded=false and aria-controls=menuId.
<button aria-expanded={open} aria-controls={menuId}>Actions</button>- open
- false
- menuId
- :r1:
- focusedElement
- Trigger
Under the Hood
Instead of passing 30 configuration props to a monolithic <Dropdown options={...} />, compound primitives compose shared state through Context or state-machine hooks.
- ID & ARIA Linking: The root primitive generates deterministic
useId()tokens, injectingaria-controlsonTriggerand matchingid+roleonContent. - Controlled vs Uncontrolled State: A
useControllableStatehook supports both internal state (defaultOpen) and external state (open+onOpenChange) without dual-source desync. - Focus & Dismissal Guards: Opening
Contenttraps or moves focus, bindsEscapeandpointerdownoutside listeners, and restores focus toTriggeron close.
const MenuContext = createContext<{ open: boolean; toggle: () => void; menuId: string } | null>(null);
function MenuRoot({ children }: { children: ReactNode }) {
const [open, setOpen] = useState(false);
const menuId = useId();
return (
<MenuContext.Provider value={{ open, toggle: () => setOpen((o) => !o), menuId }}>
{children}
</MenuContext.Provider>
);
}Problem Genealogy
- 2016 (Monolithic UI Kits): Bootstrap/Material wrappers shipped 60–120 KB of opinionated CSS and rigid props, requiring brittle
!importantoverrides for custom design systems. - 2020 (Headless Compound Primitives): Radix, Reach UI, and React Aria extracted WAI-ARIA APG state machines into unstyled composable primitives.
- 2024 (Native
popover&dialogConvergence): Native HTML top-layer APIs offloaded z-index stacking and light-dismissal from JS portals to Blink/Gecko C++ engines.
Production Pitfalls
- Swallowing
refor Event Handlers onasChild: Cloning a custom child element without mergingrefandonClickbreaks trigger dismissal and focus restoration. - Animating Unmounted Portals: Unmounting
Contentimmediately whenopenflipsfalsekills CSS exit transitions unlessforceMountor@starting-style+Presencewaits foranimationend.
- When not to use a JS headless library: Never import a 15 KB JS popover/dialog primitive for simple non-modal disclosure tooltips or basic alerts where native HTML
<dialog>orpopover="auto"handles focus and dismissal in 0 KB of JS.
Connections & Logical Next Steps
Headless primitives wire aria-expanded, aria-controls, and unique IDs automatically across compound parts.
Composite widgets like menus and tabs manage arrow-key focus via roving tabindex contracts.
Floating popovers and dialogs promote into the browser top layer or portals to escape overflow clipping.