Headless Components: Separate Logic from UI

Why it exists

As UI components evolve, they accumulate complex logic for state management, accessibility, keyboard navigation, and asynchronous data. This logic often becomes tightly coupled with the visual presentation, making the component difficult to test, maintain, and reuse with a different look.

The mental model

A Headless Component is like an engine without a car body. It provides all the power and functionality (the 'brain') but no visual representation (the 'looks'). You get a pre-built, battle-tested engine, and you are free to design and build any car body you want around it, ensuring the core mechanics are consistent.

How it works

This pattern is often implemented as a custom hook in React (e.g., useDropdown). The hook manages all the non-visual logic internally. It returns an object containing state variables (like isOpen or selectedIndex) and props-getter functions (getMenuProps, getItemProps). You call this hook in your own component and spread the returned props onto your custom JSX elements to wire up the logic to your UI.

When to use it

Use this pattern for foundational UI elements that require complex logic but need to appear differently across an application. It's perfect for dropdowns, modals, tabs, and accordions where you want to enforce consistent behavior and accessibility standards while allowing for complete visual freedom. It promotes reusability without sacrificing design flexibility.

When not to use it

Avoid this pattern for simple, one-off components where the logic and UI are trivial. If a pre-styled component from a library already fits your design system and functional needs, using it is more direct. The headless approach adds an extra layer of implementation that is only justified by the need for high reusability and visual customization.

One canonical example

A headless dropdown hook manages the open/close state, keyboard navigation (arrow keys, Enter, Escape), and ARIA attributes. It exposes state like isOpen and functions to control it. A developer consumes this hook to build a fully custom dropdown, applying their own branding and styles to the div and button elements, while the hook ensures the behavior is robust and accessible.