# npm
npm install @headlessui/react
 
# pnpm（推荐）
pnpm add @headlessui/react
 
# yarn
yarn add @headlessui/react
 
# Vue 版本
pnpm add @headlessui/vue

# 安装 Tailwind CSS（如尚未安装）
pnpm add -D tailwindcss @tailwindcss/postcss
 
# 在 postcss.config.js 或 postcss.config.mjs 中配置

// postcss.config.mjs
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

import { Menu, MenuButton, MenuItem, MenuItems } from '@headlessui/react'
 
export default function Example() {
  return (
    <Menu>
      <MenuButton className="rounded-md bg-indigo-600 px-4 py-2 text-sm font-medium text-white hover:bg-indigo-500">
        选项菜单
      </MenuButton>
 
      <MenuItems
        anchor="bottom"
        className="mt-1 w-48 origin-top-right rounded-xl border border-gray-200 bg-white p-1 shadow-lg"
      >
        <MenuItem>
          {({ focus }) => (
            <button className={`block w-full rounded-lg px-3 py-1.5 text-sm text-gray-800 ${focus ? 'bg-indigo-100' : ''}`}>
              编辑资料
            </button>
          )}
        </MenuItem>
        <MenuItem>
          {({ focus }) => (
            <button className={`block w-full rounded-lg px-3 py-1.5 text-sm text-gray-800 ${focus ? 'bg-indigo-100' : ''}`}>
              设置
            </button>
          )}
        </MenuItem>
        <MenuItem>
          {({ focus }) => (
            <button className={`block w-full rounded-lg px-3 py-1.5 text-sm text-red-600 ${focus ? 'bg-red-50' : ''}`}>
              退出登录
            </button>
          )}
        </MenuItem>
      </MenuItems>
    </Menu>
  )
}

<template>
  <Menu>
    <MenuButton
      class="rounded-md bg-indigo-600 px-4 py-2 text-sm font-medium text-white hover:bg-indigo-500"
    >
      选项菜单
    </MenuButton>
 
    <MenuItems
      anchor="bottom"
      class="mt-1 w-48 origin-top-right rounded-xl border border-gray-200 bg-white p-1 shadow-lg"
    >
      <MenuItem v-slot="{ focus }">
        <button
          :class="[
            'block w-full rounded-lg px-3 py-1.5 text-sm text-gray-800',
            focus ? 'bg-indigo-100' : ''
          ]"
        >
          编辑资料
        </button>
      </MenuItem>
    </MenuItems>
  </Menu>
</template>
 
<script setup>
import { Menu, MenuButton, MenuItem, MenuItems } from '@headlessui/vue'
</script>

<ListboxOptions anchor="bottom start" offset={8}>
  {/* 自动定位在触发器下方，处理边界碰撞 */}
</ListboxOptions>

<Transition
  show={isOpen}
  enter="transition ease-out duration-200"
  enterFrom="opacity-0 scale-95"
  enterTo="opacity-100 scale-100"
  leave="transition ease-in duration-150"
  leaveFrom="opacity-100 scale-100"
  leaveTo="opacity-0 scale-95"
>
  {/* 需要动画的元素 */}
</Transition>

// 非受控（简单场景）
<Listbox>
  <ListboxButton>Select</ListboxButton>
  <ListboxOptions>...</ListboxOptions>
</Listbox>
 
// 受控（复杂状态管理）
<Listbox value={selected} onChange={setSelected}>
  <ListboxButton>{selected.name}</ListboxButton>
  <ListboxOptions>...</ListboxOptions>
</Listbox>

<MenuButton as="a" href="/settings">
  设置链接
</MenuButton>
 
<ListboxButton as={Fragment}>
  <button className="custom-btn">自定义按钮</button>
</ListboxButton>

# 克隆仓库
git clone https://github.com/tailwindlabs/headlessui.git
cd headlessui
 
# 安装依赖
pnpm install
 
# 运行测试
pnpm test
 
# 构建
pnpm build
 
# 运行 playground（React）
pnpm --filter @headlessui/react-playground dev
 
# 运行 playground（Vue）
pnpm --filter @headlessui/vue-playground dev
 
# 类型检查
pnpm typecheck
 
# Lint
pnpm lint

// components/CustomSelect.tsx
import {
  Listbox,
  ListboxButton,
  ListboxOption,
  ListboxOptions,
} from '@headlessui/react'
import { ChevronDownIcon } from '@heroicons/react/20/solid'
 
interface CustomSelectProps<T> {
  label: string
  value: T
  options: { value: T; label: string }[]
  onChange: (value: T) => void
}
 
export function CustomSelect<T>({
  label,
  value,
  options,
  onChange,
}: CustomSelectProps<T>) {
  return (
    <Listbox value={value} onChange={onChange}>
      <Label className="block text-sm font-medium text-gray-700">
        {label}
      </Label>
      <ListboxButton className="relative w-full cursor-default rounded-lg bg-white py-2 pl-3 pr-10 text-left shadow-md border border-gray-300">
        {options.find(o => o.value === value)?.label}
        <ChevronDownIcon className="absolute right-3 top-1/2 -translate-y-1/2 h-5 w-5 text-gray-400" />
      </ListboxButton>
      <ListboxOptions
        anchor="bottom"
        className="w-[var(--button-width)] rounded-xl bg-white p-1 shadow-lg border border-gray-200"
      >
        {options.map(option => (
          <ListboxOption
            key={String(option.value)}
            value={option.value}
            className={({ active, selected }) =>
              `relative cursor-default select-none py-2 pl-10 pr-4 rounded-lg ${
                active ? 'bg-indigo-100 text-indigo-900' : 'text-gray-900'
              } ${selected ? 'font-medium' : 'font-normal'}`
            }
          >
            {({ selected }) => (
              <>
                {selected && (
                  <span className="absolute left-3 top-1/2 -translate-y-1/2 text-indigo-600">
                    ✓
                  </span>
                )}
                {option.label}
              </>
            )}
          </ListboxOption>
        ))}
      </ListboxOptions>
    </Listbox>
  )
}

import { Controller, useForm } from 'react-hook-form'
import { Listbox, ListboxButton, ListboxOption, ListboxOptions } from '@headlessui/react'
 
function FormExample() {
  const { control, handleSubmit } = useForm()
 
  return (
    <form onSubmit={handleSubmit(data => console.log(data))}>
      <Controller
        name="country"
        control={control}
        rules={{ required: '请选择国家' }}
        render={({ field: { onChange, value } }) => (
          <Listbox value={value} onChange={onChange}>
            <ListboxButton>选择国家</ListboxButton>
            <ListboxOptions anchor="bottom">
              <ListboxOption value="cn">中国</ListboxOption>
              <ListboxOption value="us">美国</ListboxOption>
              <ListboxOption value="jp">日本</ListboxOption>
            </ListboxOptions>
          </Listbox>
        )}
      />
    </form>
  )
}

// 使用 CSS 变量控制动画时长，便于主题统一
<Transition
  show={isOpen}
  enter="transition duration-200 ease-out"
  enterFrom="opacity-0 translate-y-1"
  enterTo="opacity-100 translate-y-0"
  leave="transition duration-150 ease-in"
  leaveFrom="opacity-100 translate-y-0"
  leaveTo="opacity-0 translate-y-1"
>
  <DialogPanel>
    {/* 对话框内容 */}
  </DialogPanel>
</Transition>

import { useState } from 'react'
import { Combobox, ComboboxInput, ComboboxOption, ComboboxOptions } from '@headlessui/react'
 
function AsyncSearch() {
  const [query, setQuery] = useState('')
  const [results, setResults] = useState([])
  const [selected, setSelected] = useState(null)
 
  async function handleQueryChange(value) {
    setQuery(value)
    if (value.length > 2) {
      const res = await fetch(`/api/search?q=${value}`)
      const data = await res.json()
      setResults(data)
    }
  }
 
  return (
    <Combobox value={selected} onChange={setSelected} immediate>
      <ComboboxInput
        className="w-full rounded-lg border border-gray-300 px-3 py-2"
        onChange={e => handleQueryChange(e.target.value)}
        placeholder="搜索用户..."
        displayValue={item => item?.name ?? ''}
      />
      <ComboboxOptions anchor="bottom" className="w-[var(--input-width)] bg-white shadow-lg rounded-xl p-1">
        {results.map(user => (
          <ComboboxOption
            key={user.id}
            value={user}
            className={({ focus }) =>
              `rounded-lg px-3 py-2 ${focus ? 'bg-indigo-100' : ''}`
            }
          >
            {user.name}
          </ComboboxOption>
        ))}
      </ComboboxOptions>
    </Combobox>
  )
}

import { Field, Label, Description, Input, FieldError } from '@headlessui/react'
 
function LoginForm() {
  const [errors, setErrors] = useState({})
 
  return (
    <form>
      <Field>
        <Label className="text-sm font-medium text-gray-700">邮箱</Label>
        <Description className="text-sm text-gray-500">
          请输入注册时使用的邮箱
        </Description>
        <Input
          className="mt-1 block w-full rounded-lg border border-gray-300 px-3 py-2 shadow-sm"
          type="email"
          name="email"
          invalid={!!errors.email}
        />
        {errors.email && (
          <FieldError className="mt-1 text-sm text-red-600">
            {errors.email}
          </FieldError>
        )}
      </Field>
    </form>
  )
}

// app/components/UserMenu.tsx
'use client'
 
import { Menu, MenuButton, MenuItem, MenuItems } from '@headlessui/react'
 
export function UserMenu() {
  return (
    <Menu>
      <MenuButton>用户菜单</MenuButton>
      <MenuItems anchor="bottom end">
        <MenuItem>
          <a href="/profile">个人资料</a>
        </MenuItem>
      </MenuItems>
    </Menu>
  )
}