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-*

(You MUST use the

anchor

(You MUST use the

transition

</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

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

onClose

<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

DialogTitle

transition

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

data-[focus]

MenuSection

MenuSeparator

Full examples: examples/menu.md

Pattern 3: Listbox (Custom Select)

Listbox replaces the native

<select>

<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

by

multiple

name

--button-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-gap:4px]"
  >
    <ComboboxOption
      value={item}
      className="px-3 py-1.5 data-[focus]:bg-blue-100"
    >
      {item.name}
    </ComboboxOption>
  </ComboboxOptions>
</Combobox>

Key points:

onClose

displayValue

virtual={{ options }}

--input-width

Full examples: examples/listbox-combobox.md

Pattern 5: Popover

Popovers display floating non-modal content. They close on outside click, Escape, or tab-away.

<Popover>
  <PopoverButton className="text-sm font-semibold data-[open]:text-blue-600">
    Solutions
  </PopoverButton>
  <PopoverPanel
    anchor="bottom start"
    transition
    className="w-80 rounded-xl bg-white p-4 shadow-lg [--anchor-gap:8px] data-[closed]:opacity-0"
  >
    <CloseButton as="a" href="/analytics">
      Analytics
    </CloseButton>
  </PopoverPanel>
</Popover>

Key points:

CloseButton

PopoverGroup

modal

Full examples: examples/popover-disclosure.md

Pattern 6: Tabs

Tab components manage tabbed content with keyboard navigation (arrow keys, Home/End).

<TabGroup>
  <TabList className="flex gap-4 border-b">
    <Tab className="px-3 py-2 text-sm data-[selected]:border-blue-500 data-[selected]:text-blue-600">
      Tab Name
    </Tab>
  </TabList>
  <TabPanels>
    <TabPanel>Content</TabPanel>
  </TabPanels>
</TabGroup>

Key points:

vertical

selectedIndex

onChange

manual

Full examples: examples/tabs.md

Pattern 7: Disclosure (Accordion)

Disclosure provides show/hide toggle for accordion-style content.

<Disclosure>
  <DisclosureButton className="flex w-full items-center justify-between rounded-lg bg-gray-100 px-4 py-2">
    Question text
    <span className="size-5 data-[open]:rotate-180" aria-hidden="true">
      &#9662;
    </span>
  </DisclosureButton>
  <DisclosurePanel
    transition
    className="px-4 pb-2 text-sm duration-200 data-[closed]:opacity-0"
  >
    Answer text
  </DisclosurePanel>
</Disclosure>

Key points: Each Disclosure manages its own state independently,

defaultOpen

data-[open]

Full examples: examples/popover-disclosure.md

Pattern 8: Switch, RadioGroup & Checkbox

Toggle, option selection, and checkbox controls with form integration.

// Switch
<Field className="flex items-center justify-between">
  <Label passive>Email notifications</Label>
  <Switch checked={enabled} onChange={setEnabled} name="notifications"
    className="group h-6 w-11 rounded-full bg-gray-200 data-[checked]:bg-blue-600">
    <span className="size-5 rounded-full bg-white group-data-[checked]:translate-x-5" />
  </Switch>
</Field>

// RadioGroup
<RadioGroup value={selected} onChange={setSelected}>
  <Radio value={option} className="data-[checked]:border-blue-500 data-[focus]:ring-2">
    <Label>{option.name}</Label>
  </Radio>
</RadioGroup>

// Checkbox
<Checkbox checked={agreed} onChange={setAgreed} name="terms"
  className="group size-5 rounded border data-[checked]:bg-blue-500">
  <svg className="size-4 text-white opacity-0 group-data-[checked]:opacity-100" viewBox="0 0 16 16" fill="currentColor">
    <path d="M12.207 4.793a1 1 0 010 1.414l-5 5a1 1 0 01-1.414 0l-2-2a1 1 0 011.414-1.414L6.5 9.086l4.293-4.293a1 1 0 011.414 0z" />
  </svg>
</Checkbox>

Key points:

passive

name

data-[checked]

group-data-[checked]

indeterminate

Full examples: examples/switch-radio.md

Pattern 9: Form Components

Headless UI v2 form primitives auto-generate IDs and wire ARIA attributes.

<Fieldset className="space-y-6">
  <Legend className="text-lg font-semibold">Shipping Details</Legend>
  <Field>
    <Label className="text-sm font-medium">Full name</Label>
    <Description className="text-sm text-gray-500">Helper text</Description>
    <Input
      name="name"
      className="data-[focus]:outline-2 data-[focus]:outline-blue-500"
    />
  </Field>
  <Field disabled>
    <Label className="data-[disabled]:opacity-50">Promo code</Label>
    <Input className="data-[disabled]:bg-gray-100" />
  </Field>
</Fieldset>

Key points: Field auto-generates

id

aria-labelledby

aria-describedby

htmlFor

Full examples: examples/forms.md

Pattern 10: Anchor Positioning

Floating panels accept an

anchor

// Position values: "top", "top start", "top end", "bottom", "bottom start", "bottom end",
//                  "left", "left start", "left end", "right", "right start", "right end"

<MenuItems anchor="bottom start" className="[--anchor-gap:8px] [--anchor-offset:4px] [--anchor-padding:12px]">

// Match trigger width
<ListboxOptions className="w-[var(--button-width)]">
<ComboboxOptions className="w-[var(--input-width)]">

// Object syntax for full control
<MenuItems anchor={{ to: "bottom start", gap: 8, offset: 4, padding: 12 }}>

CSS Variables:

--anchor-gap

--anchor-offset

--anchor-padding

--button-width

--input-width

Pattern 11: Data Attributes for Styling

Headless UI v2 exposes data attributes on all components for CSS-based state styling. Preferred over render props.

data-open

data-closed

data-focus

data-selected

data-checked

data-disabled

data-hover

data-active

// Direct styling
<MenuItem><button className="data-[focus]:bg-blue-100 data-[disabled]:opacity-50">Edit</button></MenuItem>

// Parent state styling with group
<Switch className="group ...">
  <span className="group-data-[checked]:translate-x-5" />
</Switch>

// Transition styling
<DialogPanel transition className="duration-200 data-[closed]:opacity-0 data-[closed]:scale-95">

<decision_framework>

Decision Framework

Component Selection

What interaction pattern do you need?

Modal blocking interaction?
  -> Dialog (close on Escape, outside click, focus trapped)

Dropdown with actions?
  -> Menu (arrow key navigation, type-ahead, auto-close on select)

Custom select (single/multi)?
  -> Listbox (keyboard navigation, form integration)

Searchable select?
  -> Combobox (text input + filterable dropdown)
  -> Large list (1000+)? -> Use virtual prop

Floating non-modal content?
  -> Popover (click to toggle, close on outside click)

Tabbed content?
  -> TabGroup (arrow key navigation, automatic ARIA)

Show/hide toggle?
  -> Disclosure (single toggle, accordion-style)

Boolean toggle?
  -> Switch (on/off, form integration)

Option selection from small set?
  -> RadioGroup (arrow key cycling, card-style options)

Custom checkbox?
  -> Checkbox (checked/unchecked/indeterminate)

Form field with auto ARIA?
  -> Field + Label + Description + Input/Select/Textarea

Transition Approach

How to animate components?

Simple fade/scale?
  -> transition prop + data-[closed] classes (recommended)

Different enter/leave animations?
  -> Stack data attributes: data-[closed]:data-[enter]: / data-[closed]:data-[leave]:

Coordinated multi-element animations?
  -> Transition + TransitionChild components

JavaScript animation library?
  -> Use static prop to disable internal state management
  -> Conditionally render based on your animation library's presence detection

</decision_framework>

<red_flags>

RED FLAGS

High Priority Issues:

• Using render props for class toggling instead of

  data-*

  attributes (breaks RSC compatibility, verbose code)
• Missing controlled state for Dialog (

  open

  and

  onClose

  are both required)
• Building manual dropdown/popover positioning instead of using the

  anchor

  prop
• Not providing DialogTitle (screen readers have no context for the dialog)

Medium Priority Issues:

• Using the legacy Transition component

  enter

  /

  enterFrom

  /

  enterTo

  /

  leave

  /

  leaveFrom

  /

  leaveTo

  class props instead of

  data-[closed]

  /

  data-[enter]

  /

  data-[leave]

  (v2.1+ pattern is simpler)
• Manually wiring

  id

  ,

  htmlFor

  ,

  aria-labelledby

  ,

  aria-describedby

  when Field/Label/Description auto-handle this
• Not using

  onClose

  callback to reset Combobox query state
• Forgetting

  multiple

  prop when Listbox/Combobox should support multiple selection

Common Mistakes:

• Filtering Combobox options inside the component instead of deriving from state (causes stale filter results)
• Using

  data-[state]

  with CSS

  transition

  but forgetting

  duration-*

  class (no visible animation)
• Nesting a Popover inside a Dialog without considering focus trap implications
• Using Menu for navigation (Menu is for actions; use links/buttons directly for navigation, or Popover for nav panels)

Gotchas and Edge Cases:

• data-hover

  is intelligently ignored on touch devices to prevent sticky hover states (this is intentional, not a bug)

• data-active

  is removed when dragging off the element (unlike CSS

  :active

  which persists)

• data-changing

  on Switch/Checkbox is only true for two animation frames (used for transition timing)
• Dialog renders in a

  #headlessui-portal-root

  container automatically (no explicit Portal component needed)
• Combobox

  onClose

  fires when dropdown closes (use it to reset query, not

  onChange

  )
• Listbox/Combobox compare objects by

  id

  field by default; use

  by

  prop for custom comparison
• Tab component renders as

  Fragment

  by default, not

  button

  (wrap content or use

  as="button"

  )
• Virtual scrolling in Combobox uses a render function on

  ComboboxOptions

  , not mapping

  ComboboxOption

  children
• Headless UI v2 is React-only; the Vue version remains at v1.x

</red_flags>

<critical_reminders>

CRITICAL REMINDERS

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-*

(You MUST use the

anchor

(You MUST use the

transition

Failure to follow these rules will break accessibility, keyboard navigation, and viewport-aware positioning.

</critical_reminders>