Headless UI Patterns

Quick Guide: Headless UI provides completely unstyled, fully accessible UI components designed for Tailwind CSS. Use compound component patterns (Menu/MenuButton/MenuItems/MenuItem), data-* attributes for styling states, built-in anchor positioning for floating elements, and the transition prop for CSS-powered animations. All components handle ARIA, keyboard navigation, and focus management automatically. Current: v2.2.9 (React only).

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST use the v2 compound component anatomy - e.g. Menu/MenuButton/MenuItems/MenuItem - never render raw divs with click handlers)

(You MUST use data-* attributes for styling states (data-open, data-focus, data-selected, data-hover, data-active) - NOT render props for class toggling)

(You MUST use the anchor prop on floating panels (MenuItems, ListboxOptions, ComboboxOptions, PopoverPanel) instead of manual positioning)

(You MUST use the transition prop with data-closed/data-enter/data-leave classes for animations - NOT the legacy Transition component enter/leave props)

</critical_requirements>

Auto-detection: Headless UI, headlessui, @headlessui/react, Dialog, DialogPanel, DialogTitle, Menu, MenuButton, MenuItems, MenuItem, Listbox, ListboxButton, ListboxOptions, ListboxOption, Combobox, ComboboxInput, ComboboxButton, ComboboxOptions, ComboboxOption, Popover, PopoverButton, PopoverPanel, TabGroup, TabList, Tab, TabPanel, Disclosure, DisclosureButton, DisclosurePanel, Switch, RadioGroup, Radio, Transition, Field, Label, Description, Input, Fieldset, Legend, Checkbox, CloseButton, data-closed, data-open, anchor positioning

When to use:

• Building accessible overlay components (dialogs, popovers, dropdowns, menus) with utility-class styling
• Creating fully custom select/combobox/listbox controls with keyboard navigation
• Implementing tabs, disclosure/accordion, switch, radio group, or checkbox with custom styling
• Needing automatic ARIA attributes, focus trapping, and keyboard handling without visual opinions

When NOT to use:

• Pre-styled component library desired (use a design system or pre-built component kit)
• Simple native HTML elements suffice (plain <select>, <input type="checkbox">, <details>)
• Non-React projects (v2 is React-only; Vue version remains at v1)
• Need asChild polymorphism or more granular primitive control (consider alternative headless libraries)

Package Installation:

npm install @headlessui/react

Examples:

• Core Patterns - Data-attribute styling, anchor positioning, transitions, as prop, useClose
• Dialog & Modal - Modal overlays, form dialogs, slide-over panels, transitions
• Menu & Dropdowns - Dropdown action menus, sections, icons, keyboard shortcuts
• Listbox & Combobox - Custom select, autocomplete, virtual scrolling
• Tabs - Horizontal/vertical tabs, controlled state, badges
• Popover & Disclosure - Floating panels, accordion, standalone transitions
• Switch, RadioGroup & Checkbox - Toggle, option selection, checkbox
• Form Components - Field, Input, Label, Fieldset, cascading disabled state

Quick API reference: reference.md

Philosophy

Headless UI provides behavior-only components: accessibility, keyboard navigation, focus management, and state handling are built in, while all visual styling is your responsibility. Style entirely via className using utility classes or any CSS approach.

Core Design Principles:

• Unstyled by default: No CSS shipped. Style entirely via className.
• Accessible out of the box: ARIA roles, attributes, and keyboard interactions are automatic.
• Compound components: Each UI pattern is composed of multiple coordinated parts (e.g., Menu + MenuButton + MenuItems + MenuItem).
• Data attributes for state: Components expose data-open, data-focus, data-selected, data-hover, data-active, data-disabled, data-checked for CSS-based state styling.
• Built-in anchor positioning: Floating panels (menus, listboxes, comboboxes, popovers) use Floating UI internally for automatic viewport-aware positioning.
• Transition support: The transition prop enables CSS transitions using data-closed, data-enter, data-leave attributes.

Core Patterns

Pattern 1: Dialog (Modal)

Dialogs are always controlled components. You manage open state and pass onClose. Focus is automatically trapped within the dialog panel.

<Dialog
  open={isOpen}
  onClose={() => setIsOpen(false)}
  className="relative z-50"
>
  <DialogBackdrop
    transition
    className="fixed inset-0 bg-black/30 duration-300 data-[closed]:opacity-0"
  />
  <div className="fixed inset-0 flex w-screen items-center justify-center p-4">
    <DialogPanel
      transition
      className="max-w-lg rounded-xl bg-white p-12 duration-300 data-[closed]:scale-95 data-[closed]:opacity-0"
    >
      <DialogTitle className="text-lg font-bold">Title</DialogTitle>
      <Description>Description text</Description>
    </DialogPanel>
  </div>
</Dialog>

Key points: open/onClose are required, DialogTitle sets aria-labelledby, transition enables CSS animations via data-[closed]

Full examples: examples/dialog.md

Pattern 2: Menu (Dropdown)

Menus provide dropdown behavior: arrow key navigation, type-ahead search, auto-close on selection.

<Menu>
  <MenuButton className="rounded-md bg-gray-800 px-4 py-2 text-white">
    Options
  </MenuButton>
  <MenuItems
    anchor="bottom start"
    transition
    className="w-52 rounded-xl bg-white p-1 shadow-lg [--anchor-gap:8px] data-[closed]:scale-95 data-[closed]:opacity-0"
  >
    <MenuItem>
      <button className="block w-full rounded-lg px-3 py-1.5 text-left data-[focus]:bg-gray-100">
        Edit
      </button>
    </MenuItem>
  </MenuItems>
</Menu>

Key points: anchor handles positioning, data-[focus] styles keyboard/mouse focus, items auto-close menu on click, use MenuSection/MenuSeparator for grouped menus

Full examples: examples/menu.md

Pattern 3: Listbox (Custom Select)

Listbox replaces the native <select> with full styling control and keyboard navigation.

<Listbox value={selected} onChange={setSelected}>
  <ListboxButton className="w-full rounded-lg py-2 pl-3 pr-10 text-left shadow-md">
    {selected.name}
  </ListboxButton>
  <ListboxOptions
    anchor="bottom"
    className="w-[var(--button-width)] rounded-xl bg-white p-1 shadow-lg [--anchor-gap:4px]"
  >
    <ListboxOption
      value={item}
      className="px-3 py-1.5 data-[focus]:bg-blue-100 data-[selected]:font-semibold"
    >
      {item.name}
    </ListboxOption>
  </ListboxOptions>
</Listbox>

Key points: Objects compared by id field by default (use by prop for custom), multiple prop for multi-select, name for form submission, --button-width matches dropdown to trigger width

Full examples: examples/listbox-combobox.md

Pattern 4: Combobox (Autocomplete)

Combobox combines a text input with a filterable dropdown. Filtering logic is your responsibility.

<Combobox value={selected} onChange={setSelected} onClose={() => setQuery("")}>
  <ComboboxInput
    displayValue={(item: Item | null) => item?.name ?? ""}
    onChange={(e) => setQuery(e.target.value)}
  />
  <ComboboxOptions
    anchor="bottom"
    className="w-[var(--input-width)] rounded-xl bg-white shadow-lg [--anchor-g