Guide · Open source
How to use Headless UI: install and build accessible components
Updated · written with AI from the project's own documentation and checked against our catalogue data
Headless UI is a library of completely unstyled, fully accessible UI components for React and Vue, designed to work with Tailwind CSS. This guide shows you how to install the right package, what the library gives you and what you still need to write yourself. By the end you will know where to start and where to find the full documentation.
Headless UItailwindlabs/headlessui · ★ 28.8k · MIT Install options & downloads Quick start
- 1Check prerequisites. Confirm that Node.js and npm are installed and that you have a React or Vue project.
- 2Install the package for your framework. Run npm install @headlessui/react@latest in a React project, or npm install @headlessui/vue@latest in a Vue project.
- 3Read the component docs. Open headlessui.com to see the available components and how each one is used.
- 4Add a component to your interface. Import the component you need and place it in your markup.
- 5Style it with Tailwind CSS. Apply your own Tailwind classes, since the components ship with no visual styling.
- 6Test keyboard and screen reader behavior. Check that the built-in accessibility behavior works in your final design.
What Headless UI is and who it is for
Headless UI provides interface building blocks such as menus and dialogs. The components include behavior and accessibility, but no visual styling, so you control the look with your own CSS, typically Tailwind CSS.
It suits React or Vue developers who want custom-designed interfaces, and teams already using Tailwind CSS who want accessible widgets that match their styling. It is not a ready-made design system, so beginners without web development experience will need to write their own markup and styles.
What you need before you install
You need Node.js and npm, plus an existing React or Vue project. The library is published as two npm packages, one for each framework.
- Node.js and npm
- A React project, or a Vue project
Install the React or Vue package
Install the package that matches your framework. These commands install the latest release.
- React: install @headlessui/react with the latest tag
- Vue: install @headlessui/vue with the latest tag
npm install @headlessui/react@latest
npm install @headlessui/vue@latestUnderstand the insiders build
The insiders build points to the latest commit on the main branch. It is available with the insiders tag. The project notes that this build does not follow semver, so its APIs are not guaranteed to match once released. Use it only if you accept that risk.
npm install @headlessui/react@insiders
npm install @headlessui/vue@insidersStyle the components with Tailwind CSS
Because the components have no styles, you add classes or CSS yourself. The README names Tailwind CSS as the intended styling approach, and the repository includes a @headlessui/tailwindcss package in its packages list. Check the official documentation at headlessui.com for the exact component APIs and how to apply styles to each part.
- Pick the components you need, such as menus or dialogs
- Apply your own Tailwind classes to the markup the components render
- Use the official docs for each component's props and states
Get help and contribute
For help, best practice discussions or feature ideas, use the project's GitHub discussions. If you want to contribute, read the contributing guide before opening a pull request.
What people use it for
- Building a custom dropdown menu in a React app that matches an existing Tailwind design
- Creating an accessible modal dialog in a Vue project without a fixed component library
- Adding keyboard-accessible widgets to a Tailwind-styled marketing or dashboard site
Frequently asked questions
How do I install Headless UI?
Install the package for your framework with npm. Use npm install @headlessui/react@latest for React or npm install @headlessui/vue@latest for Vue. You need Node.js and npm, plus an existing project.
Is Headless UI free to use?
The project is released under the MIT licence. The source does not give further licensing details, so check the repository's licence file for the full terms.
Does Headless UI work with Vue and React?
Yes. The README lists two packages, @headlessui/react and @headlessui/vue. The source does not mention other frameworks.
Does Headless UI come with styles?
No. The README describes the components as completely unstyled, so you style them yourself, typically with Tailwind CSS.
What are alternatives to Headless UI?
Comparable projects include Radix UI, React Aria, Reach UI and Ark UI. Compare them based on the framework you use and how much styling control you need.
Where can I get help with Headless UI?
Use the GitHub discussions page for help, best practice questions and feature ideas. The full documentation is at headlessui.com.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Headless UI suits React or Vue developers who want accessible components and already plan to style them with Tailwind CSS. It is a poor fit if you want good-looking components out of the box or work with a framework other than React or Vue.
Install options & downloads