HeadlessUI React

1. Overview

HeadlessUI provides completely unstyled, fully accessible UI components for React. Components handle all the complex accessibility and interaction logic — you provide all the styling. 38 playground examples are available via MCP.

All HeadlessUI React examples are available through the frontend-components MCP server under the headlessui-react framework.

2. Installation

npm install @headlessui/react

Optional (for icons):

npm install @heroicons/react

3. MCP Workflow

3.1 Browse Available Examples

list_components(framework: "headlessui-react")

Components: combobox, dialog, disclosure, listbox, menu, popover, radio-group, switch, tabs, transitions, combinations, suspense.

3.2 Get Example Code

get_component(framework: "headlessui-react", category: "components", component_type: "dialog", variant: "dialog")
get_component(framework: "headlessui-react", category: "components", component_type: "menu", variant: "menu")
get_component(framework: "headlessui-react", category: "components", component_type: "combobox", variant: "combobox")

3.3 Search

search_components(query: "listbox", framework: "headlessui-react")
search_components(query: "transition", framework: "headlessui-react")

4. Core API Patterns

4.1 Compound Components

HeadlessUI uses compound component patterns. Parent manages state, children render UI:

import { Menu, MenuButton, MenuItems, MenuItem } from "@headlessui/react";

function MyMenu() {
  return (
    <Menu>
      <MenuButton className="...">Options</MenuButton>
      <MenuItems className="...">
        <MenuItem>
          <a className="..." href="/edit">Edit</a>
        </MenuItem>
        <MenuItem>
          <a className="..." href="/delete">Delete</a>
        </MenuItem>
      </MenuItems>
    </Menu>
  );
}

4.2 The as Prop

Change the rendered element for any component:

<MenuButton as="div" className="...">Options</MenuButton>
<MenuItem as="button" className="...">Edit</MenuItem>
<DialogPanel as="form" className="...">...</DialogPanel>

4.3 Render Props / Data Attributes

HeadlessUI exposes component state through data attributes for styling:

<MenuItem>
  <a
    className="data-[focus]:bg-blue-100 data-[disabled]:opacity-50"
    href="/edit"
  >
    Edit
  </a>
</MenuItem>

<Switch
  checked={enabled}
  onChange={setEnabled}
  className="data-[checked]:bg-blue-600 bg-gray-200"
/>

Key data attributes:

Attribute	Components	Meaning
data-[focus]	MenuItem, ListboxOption, ComboboxOption	Item has focus
data-[active]	MenuItem, ListboxOption	Item is active
data-[selected]	ListboxOption, ComboboxOption, Tab	Item is selected
data-[checked]	Switch, RadioGroupOption	Item is checked
data-[open]	Disclosure, Popover, Menu, Dialog	Panel is open
data-[disabled]	Most components	Item is disabled
data-[closed]	Transition targets	Element is closed/hidden

5. Component Reference

5.1 Dialog (Modal)

import { Dialog, DialogPanel, DialogTitle, DialogBackdrop } from "@headlessui/react";

function MyDialog({ isOpen, onClose }) {
  return (
    <Dialog open={isOpen} onClose={onClose} className="relative z-50">
      <DialogBackdrop className="fixed inset-0 bg-black/30" />
      <div className="fixed inset-0 flex w-screen items-center justify-center p-4">
        <DialogPanel className="max-w-lg rounded bg-white p-6 shadow-xl">
          <DialogTitle className="text-lg font-bold">Title</DialogTitle>
          <p>Content here</p>
          <button onClick={onClose}>Close</button>
        </DialogPanel>
      </div>
    </Dialog>
  );
}

Key features:

• Focus trapping — focus stays within dialog
• Scroll locking — page scroll disabled when open
• Click outside to close (default)
• Escape key to close (default)

5.2 Menu (Dropdown)

import { Menu, MenuButton, MenuItems, MenuItem } from "@headlessui/react";

<Menu>
  <MenuButton className="rounded bg-gray-100 px-3 py-2">Options</MenuButton>
  <MenuItems
    anchor="bottom start"
    className="rounded bg-white shadow-lg ring-1 ring-black/5"
  >
    <MenuItem>
      <button className="block w-full px-4 py-2 text-left data-[focus]:bg-gray-100">
        Edit
      </button>
    </MenuItem>
    <MenuItem>
      <button className="block w-full px-4 py-2 text-left data-[focus]:bg-gray-100">
        Delete
      </button>
    </MenuItem>
  </MenuItems>
</Menu>

5.3 Listbox (Select)

import { Listbox, ListboxButton, ListboxOptions, ListboxOption } from "@headlessui/react";

function MySelect({ value, onChange, options }) {
  return (
    <Listbox value={value} onChange={onChange}>
      <ListboxButton className="...">{value.name}</ListboxButton>
      <ListboxOptions anchor="bottom" className="...">
        {options.map((option) => (
          <ListboxOption
            key={option.id}
            value={option}
            className="data-[focus]:bg-blue-100 cursor-pointer px-4 py-2"
          >
            {option.name}
          </ListboxOption>
        ))}
      </ListboxOptions>
    </Listbox>
  );
}

5.4 Combobox (Autocomplete)

import { Combobox, ComboboxInput, ComboboxOptions, ComboboxOption, ComboboxButton } from "@headlessui/react";

function MyCombobox({ value, onChange, options }) {
  const [query, setQuery] = useState("");
  const filtered = query === ""
    ? options
    : options.filter((o) => o.name.toLowerCase().includes(query.toLowerCase()));

  return (
    <Combobox value={value} onChange={onChange} onClose={() => setQuery("")}>
      <div className="relative">
        <ComboboxInput
          className="..."
          displayValue={(o) => o?.name}
          onChange={(e) => setQuery(e.target.value)}
        />
        <ComboboxButton className="absolute inset-y-0 right-0 px-2.5">▼</ComboboxButton>
      </div>
      <ComboboxOptions anchor="bottom" className="...">
        {filtered.map((option) => (
          <ComboboxOption key={option.id} value={option} className="data-[focus]:bg-blue-100 px-4 py-2">
            {option.name}
          </ComboboxOption>
        ))}
      </ComboboxOptions>
    </Combobox>
  );
}

5.5 Switch (Toggle)

import { Switch } from "@headlessui/react";

<Switch
  checked={enabled}
  onChange={setEnabled}
  className="group relative inline-flex h-6 w-11 shrink-0 cursor-pointer rounded-full bg-gray-200 transition-colors data-[checked]:bg-blue-600"
>
  <span className="pointer-events-none inline-block size-5 translate-x-0.5 rounded-full bg-white shadow ring-0 transition-transform group-data-[checked]:translate-x-5" />
</Switch>

5.6 Disclosure (Accordion)

import { Disclosure, DisclosureButton, DisclosurePanel } from "@headlessui/react";

<Disclosure>
  <DisclosureButton className="flex w-full justify-between rounded-lg bg-gray-100 px-4 py-2">
    Section Title
  </DisclosureButton>
  <DisclosurePanel className="px-4 py-2 text-gray-500">
    Content here
  </DisclosurePanel>
</Disclosure>

5.7 Popover

import { Popover, PopoverButton, PopoverPanel } from "@headlessui/react";

<Popover className="relative">
  <PopoverButton className="...">Info</PopoverButton>
  <PopoverPanel anchor="bottom" className="...">
    Popover content
  </PopoverPanel>
</Popover>

5.8 RadioGroup

import { RadioGroup, Radio, Label, Description } from "@headlessui/react";

<RadioGroup value={selected} onChange={setSelected}>
  {options.map((option) => (
    <Radio
      key={option.id}
      value={option}
      className="group relative flex cursor-pointer rounded-lg border px-5 py-4 data-[checked]:bg-blue-50 data-[checked]:border-blue-500"
    >
      <Label className="font-medium">{option.name}</Label>
      <Description className="text-gray-500">{option.desc}</Description>
    </Radio>
  ))}
</RadioGroup>

5.9 Tabs

import { TabGroup, TabList, Tab, TabPanels, TabPanel } from "@headlessui/react";

<TabGroup>
  <TabList className="flex gap-4">
    <Tab className="rounded-full px-3 py-1 data-[selected]:bg-blue-100 data-[selected]:text-blue-700">
      Tab 1
    </Tab>
    <Tab className="rounded-full px-3 py-1 data-[selected]:bg-blue-100 data-[selected]:text-blue-700">
      Tab 2
    </Tab>
  </TabList>
  <TabPanels className="mt-3">
    <TabPanel>Panel 1</TabPanel>
    <TabPanel>Panel 2</TabPanel>
  </TabPanels>
</TabGroup>

6. Transitions

HeadlessUI includes a built-in Transition component. Use Tailwind classes for animations:

import { Transition } from "@headlessui/react";

<Transition
  show={isOpen}
  enter="transition-opacity duration-150"
  enterFrom="opacity-0"
  enterTo="opacity-100"
  leave="transition-opacity duration-150"
  leaveFrom="opacity-100"
  leaveTo="opacity-0"
>
  <div>Animated content</div>
</Transition>

Many components support built-in transition via transition prop:

<MenuItems
  transition
  className="transition duration-100 ease-in data-[closed]:scale-95 data-[closed]:opacity-0"
>

7. Floating UI (Positioning)

HeadlessUI uses Floating UI internally for positioning dropdown panels. Control with the anchor prop:

<MenuItems anchor="bottom start">  {/* Below, left-aligned */}
<MenuItems anchor="bottom end">    {/* Below, right-aligned */}
<MenuItems anchor="top start">     {/* Above, left-aligned */}
<ListboxOptions anchor="bottom">   {/* Below, centered */}

Anchor values: top, right, bottom, left with optional start/end alignment.

Add gap with anchor={{ to: 'bottom', gap: 4 }}.

8. Accessibility Features

HeadlessUI handles these automatically:

• ARIA attributes (role, aria-expanded, aria-haspopup, aria-labelledby, etc.)
• Keyboard navigation (arrow keys, Enter, Space, Escape, Home, End)
• Focus management (trapping in dialogs, return focus on close)
• Screen reader announcements
• Click-outside-to-close for menus, popovers, dialogs

9. Common Patterns

9.1 Controlled vs Uncontrolled

// Controlled — you manage state
const [selected, setSelected] = useState(options[0]);
<Listbox value={selected} onChange={setSelected}>

// Uncontrolled — HeadlessUI manages state
<Listbox defaultValue={options[0]} onChange={(val) => console.log(val)}>

9.2 Form Integration

HeadlessUI components work with native forms when given a name:

<Listbox name="country" value={selected} onChange={setSelected}>
  {/* renders a hidden input with the selected value */}
</Listbox>

9.3 Disabled Items

<MenuItem disabled>
  <button className="data-[disabled]:opacity-50" disabled>
    Can't click
  </button>
</MenuItem>

10. Workflow Summary

Step	Action
1. Pick component	Dialog, Menu, Listbox, Combobox, Switch, etc.
2. Fetch example	get_component(framework: "headlessui-react", ...)
3. Import	import { Component } from "@headlessui/react"
4. Style with Tailwind	Use className + data attributes for states
5. Add transitions	Use transition prop or Transition component
6. Position	Use anchor prop for dropdowns/popovers