Headless UI — Unstyled Accessible UI Components for React and Vue

Introduction

Headless UI is an open-source component library by the Tailwind Labs team that provides fully accessible, completely unstyled UI primitives. It handles the complex accessibility logic, keyboard navigation, and focus management so you can apply any visual design without fighting opinionated default styles.

What Headless UI Does

• Provides unstyled, WAI-ARIA compliant components for common UI patterns
• Handles keyboard navigation, focus trapping, and screen reader announcements automatically
• Ships components for menus, listboxes, comboboxes, dialogs, disclosure panels, tabs, radio groups, and switches
• Offers render-prop and slot-based APIs for full control over rendered HTML
• Supports both React and Vue with dedicated packages

Architecture Overview

Each component is a state machine that manages open/closed state, active item tracking, and focus management. Components expose render props (React) or scoped slots (Vue) that pass down state like open, active, selected, and disabled. No CSS is bundled; all styling is left to the consumer. Transitions are handled via a built-in Transition component that coordinates enter/leave classes.

Self-Hosting & Configuration

• Install @headlessui/react for React or @headlessui/vue for Vue
• Import individual components and compose them in your JSX or template
• Apply styles using Tailwind utility classes, CSS modules, styled-components, or plain CSS
• Use the as prop to change the underlying HTML element any component renders
• Wrap opening/closing animations with the built-in Transition component and configure enter/leave classes

Key Features

• Zero styling opinions: compatible with Tailwind CSS, CSS-in-JS, or any approach
• WAI-ARIA patterns implemented correctly out of the box with no extra configuration
• Composable API where each component part is a separate importable piece
• Built-in transition support for coordinated open/close animations
• TypeScript-first with full generic type inference for custom elements via as

Comparison with Similar Tools

• Radix Primitives — Similar headless approach for React; Headless UI also supports Vue and pairs natively with Tailwind
• Reach UI — Accessible React components but with default styles; no longer actively maintained
• Ariakit — Flexible low-level primitives; Headless UI offers higher-level compound components
• Mantine — Full-featured styled library; Headless UI gives complete styling freedom
• shadcn/ui — Built on Radix; Headless UI is the Tailwind Labs equivalent with its own component set

FAQ

Q: Do I need Tailwind CSS to use Headless UI? A: No. The components are completely unstyled and work with any CSS approach. Tailwind is recommended but not required.

Q: Does Headless UI handle animations? A: Yes. The built-in Transition component lets you define enter/leave CSS classes for coordinated open/close animations.

Q: Can I customize the HTML elements rendered? A: Yes. Every component accepts an as prop that lets you swap the default element for any HTML tag or custom component.

Q: Is Headless UI production-ready? A: Yes. It is maintained by the Tailwind Labs team and used in production by Tailwind UI and many large-scale applications.

Sources

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