Headless UI — Unstyled Accessible UI Components for Tailwind CSS

Introduction

Headless UI is a set of completely unstyled, accessible UI components built by the Tailwind Labs team. It provides the complex behavior and accessibility logic for common interactive patterns — menus, dialogs, listboxes, comboboxes, tabs — while leaving all visual styling to you and your Tailwind classes.

What Headless UI Does

• Implements accessible interaction patterns for menus, dialogs, popovers, comboboxes, and more
• Manages focus trapping, keyboard navigation, ARIA attributes, and screen reader announcements
• Ships render-prop and slot-based APIs for React and Vue respectively
• Provides transition components for coordinating enter/leave animations
• Leaves all styling decisions to the consumer, with no built-in CSS or opinions

Architecture Overview

Headless UI components are built as controlled state machines that manage open/close state, focus management, and ARIA semantics internally. Each component exposes its state through render props or slot props, allowing consumers to apply styles conditionally. The library uses Floating UI internally for positioning floating elements like menus and popovers. Components are written in TypeScript with separate packages for React and Vue.

Self-Hosting & Configuration

• Install @headlessui/react or @headlessui/vue depending on your framework
• Import individual components — the library is fully tree-shakable
• Apply Tailwind CSS classes directly on component elements using render props for state-based styling
• Use the <Transition> component to animate enter/leave states with Tailwind transition classes
• Compose multiple headless components together for complex patterns like combobox with popover

Key Features

• Full WAI-ARIA compliance with keyboard navigation, focus management, and screen reader support
• Zero visual opinions — style every component exactly how your design requires
• Tight Tailwind CSS integration with state-based class application via render props
• Built and maintained by the Tailwind Labs team alongside Tailwind CSS itself
• TypeScript definitions for all components with accurate prop and state types

Comparison with Similar Tools

• Radix UI — similar headless approach with more components; slightly larger API surface
• DaisyUI — pre-styled Tailwind components; faster to use but less design flexibility
• shadcn/ui — copy-paste components built on Radix and Tailwind; higher-level but React-only
• Ariakit — comparable accessible primitives; framework-agnostic but smaller community
• Mantine — fully styled component library with its own design system; not headless

FAQ

Q: What frameworks does Headless UI support? A: Headless UI ships separate packages for React (@headlessui/react) and Vue (@headlessui/vue). There is no Angular or Svelte version.

Q: Do I need Tailwind CSS to use Headless UI? A: No. Headless UI works with any CSS approach. It pairs naturally with Tailwind because both come from Tailwind Labs, but you can use vanilla CSS, CSS modules, or any styling solution.

Q: How many components does Headless UI include? A: Headless UI provides around 12 component patterns: Menu, Listbox, Combobox, Switch, Dialog, Popover, Radio Group, Tabs, Disclosure, Transition, Checkbox, and Field.

Q: Is Headless UI production-ready? A: Yes. It is used in production by Tailwind UI and many other projects. The library is actively maintained with regular releases.

Sources

• https://github.com/tailwindlabs/headlessui
• https://headlessui.com/