Headless UI — Unstyled Accessible UI Components for React and Vue

Introduction

Headless UI is a library of unstyled, accessible UI components built by Tailwind Labs. It handles the complex behavior and accessibility logic of interactive widgets — menus, dialogs, listboxes, comboboxes — while leaving all visual styling to you. It pairs naturally with Tailwind CSS but works with any styling approach.

What Headless UI Does

• Provides accessible dropdown menus, dialogs, popovers, and disclosure panels
• Manages focus trapping, keyboard navigation, and ARIA attributes automatically
• Ships components for React and Vue with identical APIs
• Supports transitions for enter/leave animations on dynamic elements
• Renders no default styles, giving full visual control to the developer

Architecture Overview

Each Headless UI component is implemented as a compound component pattern (React) or renderless component (Vue). The library maintains internal state machines for open/close transitions, focus management, and selection tracking. Components communicate via React context or Vue provide/inject, and render using render props or slots so developers control the exact DOM structure.

Self-Hosting & Configuration

• Install the React or Vue package from npm
• Import individual components — the library is fully tree-shakeable
• Apply styling via Tailwind CSS utility classes, CSS modules, or any approach
• Use the built-in Transition component for animated mount/unmount
• Combine with Tailwind CSS and Heroicons for a complete design system

Key Features

• WAI-ARIA compliant with keyboard navigation and screen reader support
• Zero default styling — bring your own design system
• Compound component API for flexible composition
• Built-in transition support for enter and leave animations
• Small bundle footprint with full tree-shaking support

Comparison with Similar Tools

• Radix UI — similar headless approach for React only; Headless UI also supports Vue
• shadcn/ui — pre-styled Radix components; Headless UI gives you full style control
• Chakra UI — comes with a built-in theme; Headless UI separates behavior from style entirely
• React Aria (Adobe) — hooks-based accessibility primitives; Headless UI provides ready-made components

FAQ

Q: Does Headless UI require Tailwind CSS? A: No. Headless UI is style-agnostic. It pairs well with Tailwind but works with any CSS framework or plain CSS.

Q: Which components are included? A: Menu, Listbox, Combobox, Switch, Dialog, Disclosure, Popover, Radio Group, Tabs, and Transition.

Q: Can I use Headless UI with Next.js server components? A: Headless UI components are client components since they manage interactive state. Mark them with the use client directive.

Q: Is Headless UI maintained by the Tailwind team? A: Yes. Headless UI is developed and maintained by Tailwind Labs as a companion project to Tailwind CSS.

Sources

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