Headless UI

Headless UI is a set of completely unstyled, fully accessible UI primitives from the Tailwind CSS team, built for React (with companion Vue and Tailwind plugin packages) and designed to integrate beautifully with Tailwind CSS. It ships fully working components — Menu, Dialog, Listbox, Combobox, Disclosure, and more — that implement correct ARIA attributes, keyboard navigation, and focus management out of the box, while leaving 100% of the visual styling to you.

Rather than wrapping opinionated markup in themeable props, Headless UI hands you render props and data attributes so every pixel is styled with your own Tailwind classes or any CSS approach. It is actively maintained by Tailwind Labs, versioned alongside Tailwind’s own ecosystem, and used by teams who want production-grade accessibility without inheriting a component library’s visual opinions.

What You Get

• A full set of interactive primitives — Menu, Listbox, Combobox, Dialog, Disclosure, Popover, Tabs, Switch, RadioGroup, and more
• WAI-ARIA compliant markup and keyboard interactions handled internally via a dedicated state-machine architecture
• Render-prop and data-attribute APIs (data-headlessui-state) for styling active/selected/open states with any CSS approach
• An official Vue port (@headlessui/vue) and a companion Tailwind CSS plugin (@headlessui/tailwindcss) for targeting component state in utility classes

Common Use Cases

• Building custom dropdown menus, comboboxes, and autocomplete inputs without reimplementing keyboard navigation
• Adding accessible modal dialogs and slide-over panels with correct focus trapping and scroll locking
• Composing design-system components (tabs, switches, radio groups) that match a Tailwind-based visual language exactly

Under The Hood

Architecture Each component pattern (Dialog, Menu, Listbox, Combobox, …) is backed by a dedicated state machine defined against an abstract Machine<State, Event> base class (src/machine.ts) that manages state via private class fields and a subscriber/selector model, with additional shared machines (e.g. a stack machine for nested dialogs) under src/machines/. A thin React binding layer (src/react-glue.tsx, useSlice) subscribes components to just the state slices they need, keeping re-renders minimal, while src/components/* wires the machine output to DOM elements through shared hooks (use-outside-click, use-escape, use-focus-trap, etc.). This separation of framework-agnostic state logic from framework bindings is also what lets the monorepo maintain parallel React and Vue implementations from a similar internal model.

Tech Stack The library is TypeScript-first (95%+ of the codebase), with peer dependencies limited to react/react-dom (^18 || ^19). Runtime dependencies are narrow and purposeful: @floating-ui/react for popover/combobox positioning, @react-aria/focus and @react-aria/interactions for battle-tested accessibility primitives, @tanstack/react-virtual for virtualized rendering of large Combobox/Listbox option lists, and a use-sync-external-store shim for concurrent-safe external store subscriptions. Builds run through a custom esbuild-based scripts/build.sh that emits dual ESM/CJS bundles plus generated .d.ts/.d.cts typings, orchestrated across the packages/* and playgrounds/* npm workspaces.

Code Quality The @headlessui/react package alone carries roughly 30 Jest test files (via jest.config.cjs, @testing-library/react, jsdom-testing-mocks, and snapshot-diff) covering nearly every component directory — dialog, combobox, listbox, menu, disclosure, and more. Prettier is configured with prettier-plugin-organize-imports and prettier-plugin-tailwindcss, and a husky + lint-staged pre-commit hook runs lint on every commit, giving the codebase consistent formatting and import ordering. Encapsulation is taken seriously even in low-level code — the Machine base class uses native TypeScript private class fields (#state, #subscribers) rather than convention-based privacy.

API Design Consumers import one named component per pattern (<Dialog>, <Menu>, <Combobox>) that renders a sensible default element but supports full polymorphism via an as prop (forwardRefWithAs/useRender utilities), and every stateful sub-part exposes its open/active/selected condition through a data-headlessui-state attribute plus render-prop children — so styling state never requires manually threading booleans through props. Getting started requires no configuration beyond install-and-import, and the same compositional shape (Root → Button/Trigger → Panel/Items) repeats across every component, which flattens the learning curve considerably once the first pattern is learned.