Design Atlas
Type
component library
Verdict
Useful
Licence
Ship licence, open source permissiveopen-source-permissiveFree. The code is MIT (repo tailwindlabs/headlessui, about 28.8k GitHub stars at review). The docs site footer says all rights are reserved by Tailwind Labs Inc
Agent channels
none
Pricing
free
Reviewed

← Atlas · Topics: components, ux-patterns

Headless UI ​

Type
component library
Verdict
Useful
Licence
Ship licence, open source permissiveopen-source-permissiveFree. The code is MIT (repo tailwindlabs/headlessui, about 28.8k GitHub stars at review). The docs site footer says all rights are reserved by Tailwind Labs Inc
Agent channels
none
Pricing
free
Reviewed

What it is ​

Headless UI is Tailwind Labs' set of unstyled, accessible components, designed to be styled with Tailwind utility classes. The React package, @headlessui/react (v2.2.10, April 2026), has 16 components. The general ones are Dropdown Menu, Disclosure, Dialog, Popover, Tabs and Transition. The form ones are Button, Checkbox, Combobox, Fieldset, Input, Listbox, Radio Group, Select, Switch and Textarea, and they share Field, Label and Description helpers. Version 2 added built-in anchor positioning for floating panels and exposes state as data attributes (data-focus, data-hover, data-open). You can style these with Tailwind's data-* variants, and render props still work. The Vue package is still on v1.7 (last released September 2024), which covers ten components and lacks newer form pieces such as Checkbox, Input, Fieldset and Select.

When to open it ​

Open it for a Tailwind project that needs a handful of solid interactive widgets (menu, listbox, combobox, dialog, tabs) and you do not want a copy-paste registry or an extra design layer. It is also a clear reference for how a small, well-scoped headless API can look.

Most useful ​

  • Combobox and Listbox: searchable and plain custom selects with keyboard navigation and multiple selection, plus virtual scrolling for long Combobox lists
  • Transition: enter and leave animations driven by data attributes, usable on its own
  • Dialog: focus trapping, scroll locking and close-on-outside-click handled for you
  • Form set: Field, Label and Description wire up IDs and ARIA links for native and custom controls
  • Anchor positioning on Menu, Listbox, Combobox and Popover panels without extra libraries

Using it with agents ​

There is no llms.txt (404 at review), no markdown versions of the docs pages, and no MCP server or CLI. Agents install the npm package and learn from the docs pages or the source on GitHub. Models know Headless UI well, but much of what they learned is v1 style (render props, Menu.Button dot notation), so ask for the v2 component names (MenuButton, MenuItems) and data-attribute styling.

Watch out for ​

  • Smaller scope than Radix or Base UI: no tooltip, toast, slider, accordion, context menu or navigation menu
  • Vue users only get the older v1 API, and it has not been released since 2024
  • Releases have slowed, with the last React release in April 2026
  • Tailwind is the intended styling method; other CSS approaches work but get little documentation

Reusable ideas ​

  • Expose interaction state as data attributes so utility classes can style focus, hover and open states directly
  • Group label, description and control in a Field wrapper that handles IDs and ARIA links automatically
  • Build anchor positioning into floating components instead of making every user add a positioning library
  • Keep a headless library small and deep rather than broad and shallow

Radix, Base UI, shadcn/ui, Inclusive Components