Headless UI

https://github.com/tailwindlabs/headlessui
Admin
Headless UI is a set of unstyled, accessible UI components for React and Vue, such as menus, dialogs...
Tokens:111,130
Snippets:540
Trust Score:8
License:MIT
Update:1 day ago
Show doc for...
Tokens:
Raw
### Example: ProfileMenu

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-menu.md

A complete usage example of the Menu components.

```APIDOC
## Example: ProfileMenu

### Description
A complete example of using Menu, MenuButton, MenuItems, MenuItem, MenuSection, MenuHeading, and MenuSeparator together to build a profile dropdown menu.

### Code
```tsx
import { Menu, MenuButton, MenuItems, MenuItem, MenuSection, MenuHeading, MenuSeparator } from '@headlessui/react'

export function ProfileMenu() {
  return (
    <Menu>
      <MenuButton>Account</MenuButton>
      <MenuItems anchor="bottom start" className="w-48">
        <MenuSection>
          <MenuHeading>User</MenuHeading>
          <MenuItem onClick={viewProfile}>View profile</MenuItem>
          <MenuItem onClick={settings}>Settings</MenuItem>
        </MenuSection>
        <MenuSeparator />
        <MenuItem onClick={signOut} className={({ focus }) => focus ? 'bg-gray-100' : ''}>
          Sign out
        </MenuItem>
      </MenuItems>
    </Menu>
  )
}
```
```

--------------------------------

### Install @headlessui/react

Source: https://github.com/tailwindlabs/headlessui/blob/main/packages/@headlessui-react/README.md

Install the @headlessui/react package via npm.

```sh
npm install @headlessui/react
```

--------------------------------

### ProfileMenu Implementation Example

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-menu.md

A complete example showing how to compose Menu, MenuButton, MenuItems, MenuSection, MenuHeading, and MenuSeparator.

```tsx
import { Menu, MenuButton, MenuItems, MenuItem, MenuSection, MenuHeading, MenuSeparator } from '@headlessui/react'

export function ProfileMenu() {
  return (
    <Menu>
      <MenuButton>Account</MenuButton>
      <MenuItems anchor="bottom start" className="w-48">
        <MenuSection>
          <MenuHeading>User</MenuHeading>
          <MenuItem onClick={viewProfile}>View profile</MenuItem>
          <MenuItem onClick={settings}>Settings</MenuItem>
        </MenuSection>
        <MenuSeparator />
        <MenuItem onClick={signOut} className={({ focus }) => focus ? 'bg-gray-100' : ''}>
          Sign out
        </MenuItem>
      </MenuItems>
    </Menu>
  )
}
```

--------------------------------

### Install @headlessui/tailwindcss

Source: https://github.com/tailwindlabs/headlessui/blob/main/packages/@headlessui-tailwindcss/README.md

Install the @headlessui/tailwindcss plugin via npm.

```sh
npm install @headlessui/tailwindcss
```

--------------------------------

### Install @headlessui/vue

Source: https://github.com/tailwindlabs/headlessui/blob/main/packages/@headlessui-vue/README.md

Install the @headlessui/vue package. This library only supports Vue 3.

```sh
npm install @headlessui/vue
```

--------------------------------

### Portal usage example

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/vue-misc.md

Example usage of the Portal component in a Vue template.

```vue
<Portal><div class="fixed top-0">…</div></Portal>
```

--------------------------------

### Field example with Label, Input, Description

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-field-components.md

Example usage of Field with Label, Input, and Description. Shows how to compose a form control with disabled and invalid props.

```tsx
import { Field, Label, Input, Description } from '@headlessui/react'

export function EmailField() {
  return (
    <Field disabled={!editable}>
      <Label>Email address</Label>
      <Input type="email" invalid={hasError} />
      <Description>We will never share this.</Description>
    </Field>
  )
}

```

--------------------------------

### useClose usage example

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-misc.md

Example of using the `useClose` hook to get a close callback and attach it to a button's onClick handler.

```tsx
import { useClose } from '@headlessui/react'

export function CancelButton() {
  let close = useClose()
  return <button onClick={close}>Cancel</button>
}
```

--------------------------------

### Portal usage example

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-misc.md

Example of using the Portal component to render children into a shared portal root. The `enabled` prop is set to `true` to enable teleporting.

```tsx
import { Portal } from '@headlessui/react'

export function Teleported({ children }) {
  return <Portal enabled>{children}</Portal>
}
```

--------------------------------

### Input

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-field-components.md

Documentation for the Input component, including its props, slot, and an example.

```APIDOC
## Input

### Description
Renders an input element with support for disabled, invalid, and autofocus states. Provides a render prop slot with state information.

### Signature
```tsx
export type InputProps<TTag extends ElementType = typeof DEFAULT_INPUT_TAG> = Props<
  TTag,
  InputRenderPropArg,
  InputPropsWeControl,
  {
    disabled?: boolean
    invalid?: boolean
    autoFocus?: boolean
  }
>
```

### Parameters
- **disabled** (`boolean`) - Default: context or `false` - Native `disabled`.
- **invalid** (`boolean`) - Default: `false` - Renders `aria-invalid="true"`.
- **autoFocus** (`boolean`) - Default: `false` - Native autofocus (bookkeeping via `useFocusRing`).
- **id** (`string`) - Default: parent-`IdProvider` id or `headlessui-input-<n>` - Connects label `htmlFor`/`aria-describedby`.

### Slot
`{ disabled, hover, focus, autofocus, invalid }` - All other props pass through to the native element (e.g. `type`, `value`, `onChange`).

### Example
```tsx
import { Input } from '@headlessui/react'

export function SearchBox() {
  return (
    <Input
      type="search"
      placeholder="Search…"
      invalid={query !== '' && results === 0}
      className={({ focus, invalid }) => (invalid ? 'border-red-500' : focus ? 'ring' : '')}
    />
  )
}
```
```

--------------------------------

### TransitionRoot usage example

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/vue-transition.md

Example usage of TransitionRoot with `:show` bound to a `visible` variable, `appear` to animate on mount, and `data-transition-*` attributes on the child element to define enter/leave classes. The `class` attribute on the root applies base transition classes.

```vue
<script setup>
import { TransitionRoot } from '@headlessui/vue'
</script>

<template>
  <TransitionRoot :show="visible" appear class="transition duration-300">
    <div
      data-transition-enter="opacity-100"
      data-transition-enter-from="opacity-0"
      data-transition-leave="opacity-0"
      data-transition-leave-to="opacity-0"
    >
      Toast content
    </div>
  </TransitionRoot>
</template>
```

--------------------------------

### Select component example

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-field-components.md

Example usage of the Select component with native option children and an invalid prop.

```tsx
import { Select } from '@headlessui/react'

export function CountrySelect() {
  return (
    <Select name="country" invalid={errors.country}>
      <option value="">Choose…</option>
      <option value="nl">Netherlands</option>
      <option value="be">Belgium</option>
    </Select>
  )
}
```

--------------------------------

### Description Example

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-label-description.md

Example of using Description inside a Field to provide helper text that is wired to the control's aria-describedby.

```tsx
import { Field, Label, Input, Description } from '@headlessui/react'

export function PasswordField() {
  return (
    <Field>
      <Label>Password</Label>
      <Input type="password" invalid={tooShort} />
      <Description>At least 8 characters.</Description>
    </Field>
  )
}
```

--------------------------------

### Transition component example

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-transition.md

Shows how to use the Transition component with show and appear props to animate a toast notification.

```tsx
import { Transition, TransitionChild } from '@headlessui/react'

export function Toast({ show, message }) {
  return (
    <Transition
      show={show}
      appear
      className="transition duration-300"
      data-transition-enter="translate-y-0 opacity-100"
      data-transition-enter-from="translate-y-4 opacity-0"
      data-transition-leave="opacity-0"
      data-transition-leave-to="opacity-0"
    >
      <span className="fixed bottom-4">{message}</span>
    </Transition>
  )
}
```

--------------------------------

### ConfirmDialog example with Dialog components

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-dialog.md

Example of a confirm dialog using Dialog, DialogPanel, DialogTitle, DialogDescription, and CloseButton. It uses initialFocus to focus the cancel button and demonstrates the basic structure of a dialog with a title, description, and action buttons.

```tsx
import { Dialog, DialogPanel, DialogTitle, DialogDescription, CloseButton } from '@headlessui/react'

export function ConfirmDialog({ open, onClose, onConfirm }) {
  return (
    <Dialog open={open} onClose={onClose} initialFocus={cancelRef}>
      <DialogPanel>
        <DialogTitle>Delete file?</DialogTitle>
        <DialogDescription>This action cannot be undone.</DialogDescription>
        <CloseButton>✕</CloseButton>
        <button ref={cancelRef} onClick={onClose}>Cancel</button>
        <button onClick={onConfirm}>Delete</button>
      </DialogPanel>
    </Dialog>
  )
}
```

--------------------------------

### Switch

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/vue-misc.md

Documentation for the Switch component, including its props, events, and usage example.

```APIDOC
## Switch

### Description
A toggle switch component that supports controlled and uncontrolled checked states, form integration, and accessibility features.

### Props
- **modelValue** (boolean) - Controlled checked state (`v-model`)
- **defaultChecked** (boolean) - Uncontrolled initial state
- **value** (string) - Submitted form value
- **form** (string) - Hidden form field
- **name** (string) - Hidden form field
- **disabled** (boolean) - Disabled state
- **tabIndex** (number) - Tab index

### Events
- **update:modelValue** - `(value: boolean)`

### Example
```vue
<Switch v-model="notifications" name="notifications" />
```
```

--------------------------------

### Combobox basic example

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/vue-combobox.md

Basic usage example for the Combobox component. Uses `v-model` with a `by` prop for object comparison, a display-value function on the input, and a custom option template that reacts to `selected` and `active` states.

```vue
<script setup>
import { Combobox, ComboboxInput, ComboboxButton, ComboboxOptions, ComboboxOption } from '@headlessui/vue'

let people = [{ id: 1, name: 'Wade' }, { id: 2, name: 'Emil' }, { id: 3, name: 'Jane' }]
let selected = ref(null)
</script>

<template>
  <Combobox v-model="selected" by="id">
    <ComboboxInput :display-value="(p) => p?.name ?? ''" />
    <ComboboxButton>⌄</ComboboxButton>
    <ComboboxOptions>
      <ComboboxOption v-for="person in people" :key="person.id" :value="person">
        <template #default="{ selected, active }">
          <span :class="selected ? 'text-white' : active ? 'bg-indigo-400' : ''">
            {{ person.name }}
          </span>
        </template>
      </ComboboxOption>
    </ComboboxOptions>
  </Combobox>
</template>
```

--------------------------------

### Menu example with MenuButton and MenuItems

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/vue-menu.md

Example usage of the Menu component with a button and items. The `disabled` prop on MenuItem prevents interaction. Clicking a non-disabled item triggers its click handler and closes the menu.

```vue
<script setup>
import { Menu, MenuButton, MenuItems, MenuItem } from '@headlessui/vue'
</script>

<template>
  <Menu>
    <MenuButton>Account</MenuButton>
    <MenuItems class="w-48">
      <MenuItem @click="viewProfile">View profile</MenuItem>
      <MenuItem @click="settings">Settings</MenuItem>
      <MenuItem disabled>Billing</MenuItem>
      <MenuItem @click="signOut">Sign out</MenuItem>
    </MenuItems>
  </Menu>
</template>
```

--------------------------------

### Select

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-field-components.md

Documentation for the Select component, including its TypeScript signature, props, render prop arguments, and a usage example.

```APIDOC
## Select

### Signature

```tsx
let DEFAULT_SELECT_TAG = 'select' as const
type SelectRenderPropArg = { disabled: boolean; hover: boolean; focus: boolean; active: boolean; autofocus: boolean; invalid: boolean }
type SelectPropsWeControl = 'aria-labelledby' | 'aria-describedby'

export type SelectProps<TTag extends ElementType = typeof DEFAULT_SELECT_TAG> = Props<
  TTag,
  SelectRenderPropArg,
  SelectPropsWeControl,
  {
    disabled?: boolean
    invalid?: boolean
    autoFocus?: boolean
  }
>
```

### Description

The `Select` component renders a native `<select>` element with Headless UI's props and render-prop support. It accepts the same option set as `Input` plus an `active` (pressed) slot flag. Native `<option>` children pass through.

### Props

- **disabled** (`boolean`) - Optional - Whether the select is disabled.
- **invalid** (`boolean`) - Optional - Whether the select is in an invalid state.
- **autoFocus** (`boolean`) - Optional - Whether the select should autofocus on mount.

### Render Prop Arguments

- **disabled** (`boolean`) - Whether the select is disabled.
- **hover** (`boolean`) - Whether the select is hovered.
- **focus** (`boolean`) - Whether the select is focused.
- **active** (`boolean`) - Whether the select is active (pressed).
- **autofocus** (`boolean`) - Whether the select has autofocus.
- **invalid** (`boolean`) - Whether the select is invalid.

### Example

```tsx
import { Select } from '@headlessui/react'

export function CountrySelect() {
  return (
    <Select name="country" invalid={errors.country}>
      <option value="">Choose…</option>
      <option value="nl">Netherlands</option>
      <option value="be">Belgium</option>
    </Select>
  )
}
```
```

--------------------------------

### Combobox

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/vue-combobox.md

Documentation for the Combobox component, including its props, events, and a usage example.

```APIDOC
## Combobox

### Description
Combobox is the root component that manages the state and behavior of the combobox pattern. It supports single and multiple selection, controlled and uncontrolled modes, and virtualized option lists.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `as` | `string \| Component` | `'template'` | Polymorphic tag |
| `modelValue` (`v-model`) | `object \| string \| number \| boolean \| null` | `undefined` | Controlled value (array when `multiple`) |
| `defaultValue` | same | `undefined` | Uncontrolled initial value |
| `by` | `string \| ((a, z) => boolean)` | `null` (`===` comparison) | Value comparison |
| `disabled` | `boolean` | `false` | Disables the combobox |
| `form` | `string` | — (optional) | Form association for hidden input |
| `name` | `string` | — (optional) | Submit value as hidden input |
| `nullable` | `boolean` | `false` | Allow `null` model value |
| `multiple` | `boolean` | `false` | Multi-select mode |
| `immediate` | `boolean` | `false` | Skip open debounce |
| `virtual` | `{ options: unknown[]; disabled?: (value) => boolean } \| null` | `null` | Virtualized option list |

### Events

| Event | Signature | Description |
|-------|-----------|-------------|
| `@update:modelValue` | `(value: any) => void` | Emitted on selection change; bind via `v-model` |

### Example

```vue
<script setup>
import { Combobox, ComboboxInput, ComboboxButton, ComboboxOptions, ComboboxOption } from '@headlessui/vue'

let people = [{ id: 1, name: 'Wade' }, { id: 2, name: 'Emil' }, { id: 3, name: 'Jane' }]
let selected = ref(null)
</script>

<template>
  <Combobox v-model="selected" by="id">
    <ComboboxInput :display-value="(p) => p?.name ?? ''" />
    <ComboboxButton>⌄</ComboboxButton>
    <ComboboxOptions>
      <ComboboxOption v-for="person in people" :key="person.id" :value="person">
        <template #default="{ selected, active }">
          <span :class="selected ? 'text-white' : active ? 'bg-indigo-400' : ''">
            {{ person.name }}
          </span>
        </template>
      </ComboboxOption>
    </ComboboxOptions>
  </Combobox>
</template>
```
```

--------------------------------

### TabGroup example with TabList and TabPanels

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-tabs.md

Example usage of TabGroup with TabList, Tab, TabPanels, and TabPanel components. Shows defaultIndex and manual props, a disabled tab, and a render prop for selected state.

```tsx
import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/react'

export function Profile() {
  return (
    <TabGroup defaultIndex={0} manual={false}>
      <TabList className="flex gap-2">
        <Tab className={({ selected }) => selected ? 'font-bold' : ''}>Account</Tab>
        <Tab>Security</Tab>
        <Tab disabled>Billing</Tab>
      </TabList>
      <TabPanels>
        <TabPanel>Account settings…</TabPanel>
        <TabPanel>Security settings…</TabPanel>
      </TabPanels>
    </TabGroup>
  )
}
```

--------------------------------

### Disclosure example

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/vue-disclosure.md

Example usage of Disclosure with default-open, a DisclosureButton, and a DisclosurePanel that conditionally renders content based on the `open` slot prop.

```vue
<script setup>
import { Disclosure, DisclosureButton, DisclosurePanel } from '@headlessui/vue'
</script>

<template>
  <Disclosure default-open>
    <DisclosureButton>What is Headless UI?</DisclosureButton>
    <DisclosurePanel>
      <template #default="{ open }">
        <p v-if="open">Completely unstyled, accessible UI components.</p>
      </template>
    </DisclosurePanel>
  </Disclosure>
</template>
```

--------------------------------

### Combobox example with object values

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-combobox.md

Example of a combobox with a custom object value, using `by="id"` for comparison and a render prop for option styling based on selected/active state.

```tsx
import { Combobox, ComboboxInput, ComboboxButton, ComboboxOptions, ComboboxOption } from '@headlessui/react'

export function PeopleCombobox() {
  return (
    <Combobox value={selected} onChange={setSelected} by="id">
      <ComboboxInput displayValue={(person) => person?.name ?? ''} />
      <ComboboxButton>⌄</ComboboxButton>
      <ComboboxOptions className="fixed">
        {people.map((person) => (
          <ComboboxOption key={person.id} value={person}>
            {({ selected, active }) => (
              <span className={selected ? 'text-white' : active ? 'bg-blue-400' : ''}>
                {person.name}
              </span>
            )}
          </ComboboxOption>
        ))}
      </ComboboxOptions>
    </Combobox>
  )
}
```

--------------------------------

### Button

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-button.md

Documentation for the Button component from @headlessui/react, including its props, render slot, and usage examples.

```APIDOC
## Button

### Description
Renders a polymorphic button element that tracks hover, focus, active, and disabled state and exposes them to render props and data attributes.

### Signature
```tsx
let DEFAULT_BUTTON_TAG = 'button' as const
// src/components/button/button.tsx:29

type ButtonRenderPropArg = {
  disabled: boolean
  hover: boolean
  focus: boolean
  active: boolean
  autofocus: boolean
}
type ButtonPropsWeControl = never

export type ButtonProps<TTag extends ElementType = typeof DEFAULT_BUTTON_TAG> = Props<
  TTag,
  ButtonRenderPropArg,
  ButtonPropsWeControl,
  {
    disabled?: boolean
    autoFocus?: boolean
    type?: 'button' | 'submit' | 'reset'
  }
>

export interface _internal_ComponentButton extends HasDisplayName {
  <TTag extends ElementType = typeof DEFAULT_BUTTON_TAG>(
    props: ButtonProps<TTag> & RefProp<typeof ButtonFn>
  ): React.JSX.Element
}
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `as` | `TTag` (`ElementType`) | `'button'` | Polymorphic tag to render |
| `disabled` | `boolean` | Inherited from `DisabledProvider` context, else `false` | Disables the button; suppresses hover/press/click behavior |
| `autoFocus` | `boolean` | `false` | Focuses the button on mount |
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | Native button type |
| `children` | `ReactNode \| ((slot) => ReactElement)` | — | When a function, receives the render slot |
| `className` | `string \| ((slot) => string)` | — | May be a function of the slot when the tag supports `className` |
| `refName` | `string` | `'ref'` | Attribute name used to forward the ref when using `as` |

Render slot (`ButtonRenderPropArg`): `{ disabled, hover, focus, active, autofocus }`.

### Return type

Renders an element (or `Fragment`) via the polymorphic renderer. Boolean slot values are exposed as `data-headlessui-state` and `data-<state>` attributes (e.g. `data-hover`, `data-focus`, `data-active`, `data-disabled`), intended for styling with the `@headlessui/tailwindcss` plugin (`ui-open`, `ui-hover`, …).

### Throws

No errors of its own. Inherits the generic Fragment-prop error from the renderer (see [`errors.md`](../errors.md)).

### Examples

```tsx
import { Button } from '@headlessui/react'

export function MyButton() {
  return (
    <Button
      disabled={false}
      onClick={() => console.log('clicked')}
      className={({ active, focus, hover }) =>
        ['bg-white', active && 'bg-black', focus && 'ring', hover && 'underline']
          .filter(Boolean)
          .join(' ')
      }
    >
      {({ hover, focus, active }) => (
        <span>hover: {hover}, focus: {focus}, active: {active}</span>
      )}
    </Button>
  )
}
```

Rendering with a custom tag and a forwarded ref:

```tsx
import { Button } from '@headlessui/react'
import { Link } from 'next/link'

export function MyLinkButton() {
  return <Button as={Link} href="/account" refName="innerRef">Account</Button>
}
```
```

--------------------------------

### Switch

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-switch.md

Documentation for the Switch component, including its props, render prop slot, and usage examples.

```APIDOC
## Switch

### Description
A toggle switch (`role="switch"` on a button), controlled or uncontrolled, with form-field integration. The `Switch` component renders a button with `role="switch"` and supports a checked state, an `onChange` callback, and optional form integration via a hidden input field.

### Signature

```tsx
let DEFAULT_SWITCH_TAG = 'button' as const
type SwitchRenderPropArg = {
  checked: boolean
  hover: boolean
  focus: boolean
  active: boolean
  autofocus: boolean
  changing: boolean
  disabled: boolean
}
type SwitchPropsWeControl = 'aria-checked' | 'aria-describedby' | 'aria-labelledby' | 'role'

export type SwitchProps<TTag extends ElementType = typeof DEFAULT_SWITCH_TAG> = Props<
  TTag,
  SwitchRenderPropArg,
  SwitchPropsWeControl,
  {
    checked?: boolean
    defaultChecked?: boolean
    onChange?: (checked: boolean) => void
    name?: string
    value?: string
    form?: string
    autoFocus?: boolean
    disabled?: boolean
    tabIndex?: number
  }
>
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `checked` | `boolean` | — | Controlled checked state |
| `defaultChecked` | `boolean` | — | Uncontrolled initial state |
| `onChange` | `(checked: boolean) => void` | — | Called with the next state on toggle |
| `name` | `string` | — | Hidden form field name; submits `value ?? 'on'` |
| `value` | `string` | — | Form value |
| `form` | `string` | — | `form` attribute for the hidden input |
| `autoFocus` | `boolean` | `false` | Focus on mount |
| `disabled` | `boolean` | context or `false` | Disables the switch |
| `tabIndex` | `number` | `0` | Rendered tabindex (`-1` becomes `0` internally, as it must remain focusable within the group) |
| `id` | `string` | `headlessui-switch-<n>` (or parent `IdProvider` id) | — |

### Slot

`{ checked, hover, focus, active, autofocus, changing, disabled }`. `changing` is a transient one-frame flag during a toggle. Space toggles; Enter submits the form via `attemptSubmit`. The hidden form field uses `type="checkbox"` override with the checked state.

### Example

```tsx
import { Switch } from '@headlessui/react'

export function NotificationsToggle() {
  let [enabled, setEnabled] = useState(true)
  return (
    <Switch
      checked={enabled}
      onChange={setEnabled}
      name="notifications"
      aria-label="Enable notifications"
      className={({ checked }) => (checked ? 'bg-indigo-600' : 'bg-gray-200')}
    >
      {({ changing }) => <span className={changing ? 'animate-pulse' : ''} />}
    </Switch>
  )
}
```

Uncontrolled usage:

```tsx
<Switch defaultChecked name="dark-mode" form="settings" />
```
```

--------------------------------

### Combobox

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-combobox.md

Documentation for the Combobox component from @headlessui/react, including its props, render slot, and usage example.

```APIDOC
## Combobox

### Description
A WAI-ARIA combobox pattern with input + button + options list, single- and multi-select, controlled values, virtualized option lists, and floating (anchored/portalled) options.

### Signature

```tsx
export type ComboboxProps<
  TValue,
  TMultiple extends boolean | undefined,
  TTag extends ElementType = typeof DEFAULT_COMBOBOX_TAG,
> = Props<
  TTag,
  ComboboxRenderPropArg<NoInfer<TValue>>,
  'value' | 'defaultValue' | 'multiple' | 'onChange' | 'by',
  {
    value?: TMultiple extends true ? EnsureArray<TValue> : TValue
    defaultValue?: TMultiple extends true ? EnsureArray<NoInfer<TValue>> : NoInfer<TValue>
    onChange?: (value: TMultiple extends true ? EnsureArray<TValue> : TValue | null) => void
    by?: ByComparator<
      TMultiple extends true ? EnsureArray<NoInfer<TValue>>[number] : NoInfer<TValue>
    >
    nullable?: boolean
    multiple?: TMultiple
    disabled?: boolean
    invalid?: boolean
    form?: string
    name?: string
    immediate?: boolean
    virtual?: {
      options: TMultiple extends true ? EnsureArray<NoInfer<TValue>> : NoInfer<TValue>[]
      disabled?: (
        value: TMultiple extends true ? EnsureArray<NoInfer<TValue>>[number] : NoInfer<TValue>
      ) => boolean
    } | null
    onClose?: () => void
    __demoMode?: boolean
  }
>
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `value` | single: `TValue`; multi: `EnsureArray<TValue>` | — | Controlled value (single values may be `null`/`undefined` — the combobox is nullable by default) |
| `defaultValue` | single: `TValue`; multi: `EnsureArray<TValue>` | — | Uncontrolled initial value (stable for lifetime) |
| `onChange` | single: `(value: TValue \| null) => void`; multi: `(value: EnsureArray<TValue>) => void` | — | Called when selection changes |
| `multiple` | `boolean` | `false` | Multi-select mode; values become arrays |
| `by` | `ByComparator<T>` | `id`-property comparison, else `===` | Property name or comparator used to compare option values |
| `immediate` | `boolean` | `false` | When `true`, opening the combobox is not debounced |
| `virtual` | `{ options: TValue[]; disabled?: (value) => boolean } \| null` | `null` | Supplies options without rendering them (used with virtual scrolling) |
| `nullable` | `boolean` | (deprecated, nullable by default) | Deprecated no-op kept for compatibility |
| `disabled` | `boolean` | context or `false` | Disables the whole control |
| `invalid` | `boolean` | `false` | Renders `aria-invalid` on related input/button |
| `form` | `string` | — | `form` attribute for the hidden form field |
| `name` | `string` | — | When set, submits the current value as a hidden input |
| `onClose` | `() => void` | — | Called when the options close |
| `__demoMode` | `boolean` | `false` | Internal flag disabling scroll-lock/inert behaviors (used by docs demos) |

Render slot: `{ open, disabled, invalid, activeIndex, activeOption, value }`.

### Throws

- `Error('Missing `options` in virtual mode')` — when `virtual` is provided without an `options` array.

### Example

```tsx
import { Combobox, ComboboxInput, ComboboxButton, ComboboxOptions, ComboboxOption } from '@headlessui/react'

export function PeopleCombobox() {
  return (
    <Combobox value={selected} onChange={setSelected} by="id">
      <ComboboxInput displayValue={(person) => person?.name ?? ''} />
      <ComboboxButton>⌄</ComboboxButton>
      <ComboboxOptions className="fixed">
        {people.map((person) => (
          <ComboboxOption key={person.id} value={person}>
            {({ selected, active }) => (
              <span className={selected ? 'text-white' : active ? 'bg-blue-400' : ''}>
                {person.name}
              </span>
            )}
          </ComboboxOption>
        ))}
      </ComboboxOptions>
    </Combobox>
  )
}
```
```

--------------------------------

### Dialog example with panel and title

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/vue-dialog.md

Example usage of the Dialog component with a panel, title, description, and close button. The `initial-focus` prop is set to a cancel button ref, and the `@close` event sets `open` to false.

```vue
<script setup>
import { Dialog, DialogPanel, DialogTitle, DialogDescription, CloseButton } from '@headlessui/vue'
</script>

<template>
  <Dialog :open="open" :initial-focus="cancelRef" @close="open = false">
    <DialogPanel>
      <DialogTitle>Delete file?</DialogTitle>
      <DialogDescription>This action cannot be undone.</DialogDescription>
      <button ref="cancelRef" @click="open = false">Cancel</button>
      <button @click="confirm">Delete</button>
    </DialogPanel>
  </Dialog>
</template>
```

--------------------------------

### useClose

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-button.md

Documentation for the useClose hook, including its signature, return value, and usage example.

```APIDOC
## useClose

### Description
`useClose` is a hook that returns the close function from the `CloseContext`. It is used internally by `CloseButton` to trigger the close action on the parent component.

### Signature
```tsx
export function useClose() {
  return useContext(CloseContext)
}
```

### Returns
- The close function from the `CloseContext`. If no `CloseProvider` is present, the default value is a no-op `() => {}`.

### Example
```tsx
import { useClose } from '@headlessui/react'

function CustomCloseButton() {
  const close = useClose()
  return <button onClick={close}>Close</button>
}
```
```

--------------------------------

### RadioGroup example with Radio options

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-radio-group.md

Example usage of RadioGroup with Radio components. Demonstrates controlled value, onChange, name prop, and rendering options with render props for checked and focus states.

```tsx
import { RadioGroup, Radio, Label, Description } from '@headlessui/react'

export function PlanPicker() {
  return (
    <RadioGroup value={plan} onChange={setPlan} name="plan">
      <Label>Billing plan</Label>
      {['free', 'pro', 'team'].map((p) => (
        <Radio key={p} value={p} disabled={p === 'team'}>
          {({ checked, focus }) => (
            <span className={checked ? 'ring-2' : focus ? 'bg-indigo-100' : ''}>{p}</span>
          )}
        </Radio>
      ))}
    </RadioGroup>
  )
}
```

--------------------------------

### FocusTrap

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-misc.md

Documentation for the FocusTrap component, including its props, features enum, and usage example.

```APIDOC
## FocusTrap

### Description
Traps keyboard and programmatic focus inside a container. Used internally by `Dialog`.

### Component
`FocusTrap`

### Props

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `initialFocus` | `MutableRefObject<HTMLElement \| null>` | — | Element to focus on mount/activation |
| `initialFocusFallback` | `MutableRefObject<HTMLElement \| null>` | — | Fallback element (e.g. the dialog shell) — skipped when tabbing |
| `features` | `FocusTrapFeatures` | `InitialFocus \| TabLock \| FocusLock \| RestoreFocus` | Bitmask; `None` during server handoff |
| `containers` | `(() => Iterable<Element>) \| MutableRefObject<Set<MutableRefObject<Element \| null>>>` | — | Additional containers considered for focus tracking |

### Features Enum

`FocusTrapFeatures` bit flags:
- `None = 0` — No features enabled.
- `InitialFocus = 1 << 0` — Move focus initially into the container.
- `TabLock = 1 << 1` — Trap `Tab` and `Shift+Tab` within the container.
- `FocusLock = 1 << 2` — Disallow programmatic focus movement outside the container.
- `RestoreFocus = 1 << 3` — Restore focus on unmount.
- `AutoFocus = 1 << 4` — Look for `data-autofocus` for initial focus.

### Usage Example

```tsx
import { FocusTrap, FocusTrapFeatures } from '@headlessui/react'

export function ModalShell({ children, initialRef }) {
  return (
    <FocusTrap initialFocus={initialRef} features={FocusTrapFeatures.All}>
      {children}
    </FocusTrap>
  )
}
```

Note: `FocusTrapFeatures.All` exists in the Vue package; the React enum defines its members as bit flags without an `All` constant — combine flags with `|`.
```

--------------------------------

### Use Dialog in Vue with boolean :open prop

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/errors.md

Vue example showing how to use the Dialog component. Errors surface at compile/setup time, so validate that the `:open` prop is a boolean.

```vue
<script setup>
import { Dialog } from '@headlessui/vue'
</script>
<!-- Vue render errors surface at compile/setup time; validate `:open` is boolean -->
<Dialog :open="Boolean(openValue)" @close="…" />
```

--------------------------------

### Field

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-field-components.md

Documentation for the Field component from @headlessui/react, including its signature, parameters, and usage example.

```APIDOC
## Field

### Description
`Field` is a form-control primitive that composes label, description, id, disabled, and form context for a control. It provides a full pipeline to descendants including `DisabledProvider`, `LabelProvider`, `DescriptionProvider`, `IdProvider`, and `FormFieldsProvider`.

### Signature
```tsx
let DEFAULT_FIELD_TAG = 'div' as const
type FieldRenderPropArg = {}
type FieldPropsWeControl = never

export type FieldProps<TTag extends ElementType = typeof DEFAULT_FIELD_TAG> = Props<
  TTag,
  FieldRenderPropArg,
  FieldPropsWeControl,
  {
    disabled?: boolean
  }
>
```

### Parameters
- **disabled** (`boolean`) - Optional - Applies `disabled`/`aria-disabled` and propagates via `DisabledProvider`. Defaults to inherited from `DisabledProvider`, else `false`.
- **as** (`ElementType`) - Optional - Polymorphic tag. Defaults to `'div'`.

### Example
```tsx
import { Field, Label, Input, Description } from '@headlessui/react'

export function EmailField() {
  return (
    <Field disabled={!editable}>
      <Label>Email address</Label>
      <Input type="email" invalid={hasError} />
      <Description>We will never share this.</Description>
    </Field>
  )
}
```
```

--------------------------------

### Input component example with invalid and className render prop

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-field-components.md

Example usage of the Input component. It uses the `invalid` prop to conditionally apply a red border when the query is non-empty and results are zero, and uses the render prop `className` to apply a ring on focus. The `type` and `placeholder` props pass through to the native input element.

```tsx
import { Input } from '@headlessui/react'

export function SearchBox() {
  return (
    <Input
      type="search"
      placeholder="Search…"
      invalid={query !== '' && results === 0}
      className={({ focus, invalid }) => (invalid ? 'border-red-500' : focus ? 'ring' : '')}
    />
  )
}
```

--------------------------------

### TabGroup

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/vue-misc.md

Documentation for the TabGroup component, including its props, events, and usage example.

```APIDOC
## TabGroup

### Description
A tab group component that manages tab state and provides keyboard navigation. Supports controlled and uncontrolled selected index.

### Props
- **selectedIndex** (number) - Controlled selected index (default `null`)
- **defaultIndex** (number) - Uncontrolled initial index (default `0`)
- **vertical** (boolean) - Vertical orientation (default `false`)
- **manual** (boolean) - Manual activation (default `false`)

### Events
- **change** - `(index: number)`

### Example
```vue
<TabGroup v-model:selected-index="active" @change="onChange">
  <TabList>
    <Tab>Account</Tab>
    <Tab disabled>Billing</Tab>
  </TabList>
  <TabPanels>
    <TabPanel>Account settings…</TabPanel>
  </TabPanels>
</TabGroup>
```
```

--------------------------------

### Basic Disclosure example

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-disclosure.md

Basic usage of Disclosure with defaultOpen and a render prop on the button and panel. The panel conditionally renders content based on the open state.

```tsx
import { Disclosure, DisclosureButton, DisclosurePanel } from '@headlessui/react'

export function Faq() {
  return (
    <Disclosure defaultOpen>
      <DisclosureButton className={({ open }) => (open ? 'font-semibold' : '')}>
        What is Headless UI?
      </DisclosureButton>
      <DisclosurePanel>
        {({ open }) => open && <p>Completely unstyled, accessible UI components.</p>}
      </DisclosurePanel>
    </Disclosure>
  )
}
```

--------------------------------

### Use ui-active and ui-not-active variants with Menu

Source: https://github.com/tailwindlabs/headlessui/blob/main/packages/@headlessui-tailwindcss/README.md

Example usage of the ui-active and ui-not-active variants with a Menu component from @headlessui/react.

```js
import { Menu } from '@headlessui/react'

function MyDropdown() {
  return (
    <Menu>
      <Menu.Button>More</Menu.Button>
      <Menu.Items>
        <Menu.Item>
          <a
            className="ui-active:bg-blue-500 ui-active:text-white ui-not-active:bg-white ui-not-active:text-black"
            href="/account-settings"
          >
            Account settings
          </a>
        </Menu.Item>
        {/* ... */}
      </Menu.Items>
    </Menu>
  )
}
```

--------------------------------

### Popover with backdrop and transition

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-popover.md

Example of a Popover with a backdrop and transition. The PopoverBackdrop and PopoverPanel both have the transition prop. The panel also has focus and static props. The className values are provided for styling.

```tsx
<Popover>
  <PopoverButton>Menu</PopoverButton>
  <PopoverBackdrop transition className="bg-black/25" />
  <PopoverPanel transition focus static className="fixed-center">
    …
  </PopoverPanel>
</Popover>
```

--------------------------------

### PopoverGroup example with Popover

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-popover.md

Example of using PopoverGroup to coordinate multiple Popovers. The PopoverGroup wraps a Popover with a button and panel. The panel uses the anchor prop and a className. This example shows the basic structure for a color picker.

```tsx
import { Popover, PopoverButton, PopoverPanel, PopoverGroup } from '@headlessui/react'

export function ColorPicker() {
  return (
    <PopoverGroup>
      <Popover>
        <PopoverButton>Select color</PopoverButton>
        <PopoverPanel anchor="bottom start" className="z-20">
          {colors.map((color) => <ColorSwatch color={color} />)}
        </PopoverPanel>
      </Popover>
    </PopoverGroup>
  )
}
```

--------------------------------

### Dialog with transition classes

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-dialog.md

Example of a dialog with transition classes. The transition prop enables transition support, and the DialogPanel uses static and data-transition-* attributes to define enter/from classes for opacity transitions.

```tsx
<Dialog open={open} onClose={setOpen} transition>
  <DialogPanel
    className="transition duration-300"
    static
    data-transition-enter="opacity-100"
    data-transition-enter-from="opacity-0"
  >
    …
  </DialogPanel>
</Dialog>
```

--------------------------------

### Legend Example

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-label-description.md

Example of using Legend inside a Fieldset to group multiple fields, with the legend id registered for aria-labelledby on the group.

```tsx
import { Fieldset, Legend, Field, Label, Input } from '@headlessui/react'

export function Address() {
  return (
    <Fieldset>
      <Legend>Address</Legend>
      <Field><Label>Street</Label><Input /></Field>
      <Field><Label>City</Label><Input /></Field>
    </Fieldset>
  )
}
```

--------------------------------

### Label Example

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-label-description.md

Example of using the Label component inside a Field with an Input. The Label automatically wires htmlFor and aria-labelledby to the control.

```tsx
import { Field, Label, Input } from '@headlessui/react'

export function NameField() {
  return (
    <Field>
      <Label>Full name</Label>
      <Input value={name} />
    </Field>
  )
}
```

--------------------------------

### MenuHeading

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-menu.md

Documentation for the MenuHeading component, including its default tag and behavior.

```APIDOC
## MenuHeading

### Description
A menu heading component that provides a label for a `MenuSection`. It renders a `header` element with `role="presentation"` and registers its id as a label for the section.

### Default Tag
`'header'`

### Behavior
Registers its id as a label for `MenuSection` and sets `role="presentation"`.
```

--------------------------------

### Controlled Switch example

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-switch.md

Example of a controlled Switch component using the checked and onChange props, with a render prop for the changing state. Demonstrates styling based on checked state.

```tsx
import { Switch } from '@headlessui/react'

export function NotificationsToggle() {
  let [enabled, setEnabled] = useState(true)
  return (
    <Switch
      checked={enabled}
      onChange={setEnabled}
      name="notifications"
      aria-label="Enable notifications"
      className={({ checked }) => (checked ? 'bg-indigo-600' : 'bg-gray-200')}
    >
      {({ changing }) => <span className={changing ? 'animate-pulse' : ''} />}
    </Switch>
  )
}
```

--------------------------------

### FocusTrap usage example with initialFocus and features

Source: https://github.com/tailwindlabs/headlessui/blob/main/_autodocs/api-reference/react-misc.md

Shows how to use the FocusTrap component with an initial focus ref and the FocusTrapFeatures.All flag. Note that FocusTrapFeatures.All is only available in the Vue package; in React, combine the individual flags with the bitwise OR operator.

```tsx
import { FocusTrap, FocusTrapFeatures } from '@headlessui/react'

export function ModalShell({ children, initialRef }) {
  return (
    <FocusTrap initialFocus={initialRef} features={FocusTrapFeatures.All}>
      {children}
    </FocusTrap>
  )
}
```
Tokens:
Raw