GitHub 儲存庫

列表框（選取）

列表框是一個很棒的基礎，可為您的應用程式建置自訂、易讀的選單選取功能，並支援健全的鍵盤導覽。

首先，透過 npm 安裝 Headless UI

npm install @headlessui/react

列表框使用 Listbox、Listbox.Button、Listbox.Options、Listbox.Option 和 Listbox.Label 元件建置。

當按下 Listbox.Button 時，它會自動開啟/關閉 Listbox.Options，當功能表開啟時，清單項目會接收焦點，並可自動透過鍵盤導覽。

import { useState } from 'react'
import { Listbox } from '@headlessui/react'

const people = [
  { id: 1, name: 'Durward Reynolds', unavailable: false },
  { id: 2, name: 'Kenton Towne', unavailable: false },
  { id: 3, name: 'Therese Wunsch', unavailable: false },
  { id: 4, name: 'Benedict Kessler', unavailable: true },
  { id: 5, name: 'Katelyn Rohan', unavailable: false },
]

function MyListbox() {
  const [selectedPerson, setSelectedPerson] = useState(people[0])

  return (
    <Listbox value={selectedPerson} onChange={setSelectedPerson}>
      <Listbox.Button>{selectedPerson.name}</Listbox.Button>
      <Listbox.Options>
        {people.map((person) => (
          <Listbox.Option
            key={person.id}
            value={person}
            disabled={person.unavailable}
          >
            {person.name}
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

Headless UI 會追蹤許多關於每個元件的狀態，例如當前選取的列表框選項、快顯視窗是開啟還是關閉，或當前哪個功能表項目是透過鍵盤處於作用中。

不過，由於這些元件是無介面的，而且開箱即用時完全沒有樣式，因此您必須自行提供每個狀態的所需樣式，才能在 UI 中「看到」此資訊。

每個元件透過 渲染道具公開其當前狀態的資訊，您可以使用這些道具有條件地套用不同樣式或渲染不同內容。

例如，Listbox.Option元件公開一個active狀態，藉此告知你該選項目前是使用滑鼠或鍵盤聚焦，以及一個selected狀態，藉此告知你該選項是否與Listbox的目前value相符。

import { useState, Fragment } from 'react'
import { Listbox } from '@headlessui/react'
import { CheckIcon } from '@heroicons/react/20/solid'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]

function MyListbox() {
  const [selectedPerson, setSelectedPerson] = useState(people[0])

  return (
    <Listbox value={selectedPerson} onChange={setSelectedPerson}>
      <Listbox.Button>{selectedPerson.name}</Listbox.Button>
      <Listbox.Options>
        {people.map((person) => (
          /* Use the `active` state to conditionally style the active option. */
          /* Use the `selected` state to conditionally style the selected option. */
          <Listbox.Option key={person.id} value={person} as={Fragment}>

            {({ active, selected }) => (
              <li
                className={`${

                  active ? 'bg-blue-500 text-white' : 'bg-white text-black'
                }`}
              >

                {selected && <CheckIcon />}
                {person.name}
              </li>
            )}
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

有關每個元件的完整 render prop API，請參閱元件 API 文件。

每個元件也透過data-headlessui-state屬性公開其目前狀態相關的資訊，你可以使用此資訊來有條件套用不同的樣式。

當render prop API中任一狀態為true時，它們會以空格分隔的字串列在此屬性中，因此你可以使用[attr~=value]形式的CSS 屬性選取器來鎖定它們。

舉例來說，下列是具有部分子Listbox.Option元件的Listbox.Options元件在 listbox 開啟，且第二個選項同時為selected和active時會產生的內容

<!-- Rendered `Listbox.Options` -->
<ul data-headlessui-state="open">
  <li data-headlessui-state="">Wade Cooper</li>
  <li data-headlessui-state="active selected">Arlene Mccoy</li>
  <li data-headlessui-state="">Devon Webb</li>
</ul>

如果你正在使用Tailwind CSS，你可以使用@headlessui/tailwindcss外掛程式來使用像ui-open:*和ui-active:*之類的修改器來鎖定此屬性。

import { useState } from 'react'
import { Listbox } from '@headlessui/react'
import { CheckIcon } from '@heroicons/react/20/solid'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]

function MyListbox() {
  const [selectedPerson, setSelectedPerson] = useState(people[0])

  return (
    <Listbox value={selectedPerson} onChange={setSelectedPerson}>
      <Listbox.Button>{selectedPerson.name}</Listbox.Button>
      <Listbox.Options>
        {people.map((person) => (
          <Listbox.Option
            key={person.id}
            value={person}

            className="ui-active:bg-blue-500 ui-active:text-white ui-not-active:bg-white ui-not-active:text-black"
          >

            <CheckIcon className="hidden ui-selected:block" />
            {person.name}
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

與僅允許你提供字串作為值的原生 HTML 表單控制項不同，Headless UI 也支援繫結複雜物件。

import { useState } from 'react'
import { Listbox } from '@headlessui/react'


const people = [
  { id: 1, name: 'Durward Reynolds', unavailable: false },
  { id: 2, name: 'Kenton Towne', unavailable: false },
  { id: 3, name: 'Therese Wunsch', unavailable: false },
  { id: 4, name: 'Benedict Kessler', unavailable: true },
  { id: 5, name: 'Katelyn Rohan', unavailable: false },
]

function MyListbox() {
  const [selectedPerson, setSelectedPerson] = useState(people[0])

  return (

    <Listbox value={selectedPerson} onChange={setSelectedPerson}>
      <Listbox.Button>{selectedPerson.name}</Listbox.Button>
      <Listbox.Options>
        {people.map((person) => (
          <Listbox.Option
            key={person.id}

            value={person}
            disabled={person.unavailable}
          >
            {person.name}
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

在將物件繫結為值時，務必確保你使用與Listbox的value相同的物件執行個體，作為對應的Listbox.Option，否則它們將無法相等，並導致 listbox 行為異常。

若要簡化使用相同物件的不同執行個體，你可以使用by prop 來根據特定欄位來比較物件，而非比較的物件識別

import { Listbox } from '@headlessui/react'

const departments = [
  { id: 1, name: 'Marketing', contact: 'Durward Reynolds' },
  { id: 2, name: 'HR', contact: 'Kenton Towne' },
  { id: 3, name: 'Sales', contact: 'Therese Wunsch' },
  { id: 4, name: 'Finance', contact: 'Benedict Kessler' },
  { id: 5, name: 'Customer service', contact: 'Katelyn Rohan' },
]


function DepartmentPicker({ selectedDepartment, onChange }) {
  return (

    <Listbox value={selectedDepartment} by="id" onChange={onChange}>
      <Listbox.Button>{selectedDepartment.name}</Listbox.Button>
      <Listbox.Options>
        {departments.map((department) => (
          <Listbox.Option key={department.id} value={department}>
            {department.name}
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

如果你想要完全控制比較物件的方式，也可以將你自己的比較函式傳遞至by prop

import { Listbox } from '@headlessui/react'

const departments = [
  { id: 1, name: 'Marketing', contact: 'Durward Reynolds' },
  { id: 2, name: 'HR', contact: 'Kenton Towne' },
  { id: 3, name: 'Sales', contact: 'Therese Wunsch' },
  { id: 4, name: 'Finance', contact: 'Benedict Kessler' },
  { id: 5, name: 'Customer service', contact: 'Katelyn Rohan' },
]


function compareDepartments(a, b) {
  return a.name.toLowerCase() === b.name.toLowerCase()
}

function DepartmentPicker({ selectedDepartment, onChange }) {
  return (
    <Listbox
      value={selectedDepartment}

      by={compareDepartments}
      onChange={onChange}
    >
      <Listbox.Button>{selectedDepartment.name}</Listbox.Button>
      <Listbox.Options>
        {departments.map((department) => (
          <Listbox.Option key={department.id} value={department}>
            {department.name}
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

若要允許在你的 listbox 中選取多重值，請使用multiple prop 並傳遞一個陣列給value，而非單一選項。

import { useState } from 'react'
import { Listbox } from '@headlessui/react'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]

function MyListbox() {

  const [selectedPeople, setSelectedPeople] = useState([people[0], people[1]])

  return (

    <Listbox value={selectedPeople} onChange={setSelectedPeople} multiple>
      <Listbox.Button>
        {selectedPeople.map((person) => person.name).join(', ')}
      </Listbox.Button>
      <Listbox.Options>
        {people.map((person) => (
          <Listbox.Option key={person.id} value={person}>
            {person.name}
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

在選取選項時，這會讓 listbox 保持開啟，而選擇任一選項則會在該選項上切換。

每當選項新增或移除時，你的onChange處理常式都會帶著包含所有選取選項的陣列呼叫。

預設情況下，Listbox 會使用按鈕內容作為螢幕閱讀軟體的標籤。如果您希望進一步控制協助性技術宣告的內容，請使用 Listbox.Label 元件。

import { useState } from 'react'
import { Listbox } from '@headlessui/react'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]

function MyListbox() {
  const [selectedPerson, setSelectedPerson] = useState(people[0])

  return (
    <Listbox value={selectedPerson} onChange={setSelectedPerson}>

      <Listbox.Label>Assignee:</Listbox.Label>
      <Listbox.Button>{selectedPerson.name}</Listbox.Button>
      <Listbox.Options>
        {people.map((person) => (
          <Listbox.Option key={person.id} value={person}>
            {person.name}
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

如果您在下拉式選單加入 name 道具，系統會呈現隱藏式 input 元素，並與您的選取值保持同步。

import { useState } from 'react'
import { Listbox } from '@headlessui/react'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]

function Example() {
  const [selectedPerson, setSelectedPerson] = useState(people[0])

  return (
    <form action="/projects/1/assignee" method="post">
      <Listbox
        value={selectedPerson}
        onChange={setSelectedPerson}

        name="assignee"
      >
        <Listbox.Button>{selectedPerson.name}</Listbox.Button>
        <Listbox.Options>
          {people.map((person) => (
            <Listbox.Option key={person.id} value={person}>
              {person.name}
            </Listbox.Option>
          ))}
        </Listbox.Options>
      </Listbox>
      <button>Submit</button>
    </form>
  )
}

這可讓您在原生 HTML <form> 中使用下拉式選單，並使用傳統的表單提交方式，如同您的下拉式選單是原生 HTML 表單控制項一般。

字串等基本值會呈現為包含該值的單一隱藏式輸入，但物件等複雜值會編碼成多個輸入，名稱會採用方括號表示法

<input type="hidden" name="assignee[id]" value="1" />
<input type="hidden" name="assignee[name]" value="Durward Reynolds" />

如果您提供 defaultValue 道具，而不是 value 道具，到 Listbox，Headless UI 會為您在內部追蹤其狀態，讓你可以將其當作 非受控元件 使用。

您可以透過 Listbox 和 Listbox.Button 元件的 value 呈現道具存取目前選取的選項。

import { Listbox } from '@headlessui/react'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]

function Example() {
  return (
    <form action="/projects/1/assignee" method="post">

      <Listbox name="assignee" defaultValue={people[0]}>
        <Listbox.Button>{({ value }) => value.name}</Listbox.Button>
        <Listbox.Options>
          {people.map((person) => (
            <Listbox.Option key={person.id} value={person}>
              {person.name}
            </Listbox.Option>
          ))}
        </Listbox.Options>
      </Listbox>
      <button>Submit</button>
    </form>
  )
}

當將下拉式選單 與 HTML 輸入表單搭配使用 時，或與使用 FormData 而不是使用 React 狀態追蹤其狀態的表單 API 搭配使用時，能簡化您的程式碼。

您提供的任何 onChange 道具仍會在元件值變更時觸發，以便您執行任何副作用，但您無須使用它來自行追蹤元件的狀態。

預設情況下，您的 Listbox.Options 執行個體的顯示/隱藏會根據追蹤在 Listbox 元件本體內的內部 open 狀態自動調整。

import { useState } from 'react'
import { Listbox } from '@headlessui/react'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]

function MyListbox() {
  const [selectedPerson, setSelectedPerson] = useState(people[0])

  return (
    <Listbox value={selectedPerson} onChange={setSelectedPerson}>
      <Listbox.Button>{selectedPerson.name}</Listbox.Button>

      {/*
        By default, the `Listbox.Options` will automatically show/hide
        when the `Listbox.Button` is pressed.
      */}
      <Listbox.Options>
        {people.map((person) => (
          <Listbox.Option key={person.id} value={person}>
            {person.name}
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

如果您希望自行處理此事（例如基於任何原因需要新增額外的包覆元素），您可以新增 static 道具到 Listbox.Options 執行個體中讓它總是呈現，並檢視 Listbox 提供的 open 呈現道具自行控制哪一個元素顯示/隱藏。

import { useState } from 'react'
import { Listbox } from '@headlessui/react'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]

function MyListbox() {
  const [selectedPerson, setSelectedPerson] = useState(people[0])

  return (
    <Listbox value={selectedPerson} onChange={setSelectedPerson}>
      {({ open }) => (
        <>
          <Listbox.Button>{selectedPerson.name}</Listbox.Button>

          {open && (
            <div>
              {/*
                Using the `static` prop, the `Listbox.Options` are always
                rendered and the `open` state is ignored.
              */}

              <Listbox.Options static>
                {people.map((person) => (
                  <Listbox.Option key={person.id} value={person}>
                    {person.name}
                  </Listbox.Option>
                ))}
              </Listbox.Options>
            </div>
          )}
        </>
      )}
    </Listbox>
  )
}

使用 disabled 道具停用 Listbox.Option。這將使其無法透過滑鼠和鍵盤選取，且按壓上下箭頭時將略過它。

import { useState } from 'react'
import { Listbox } from '@headlessui/react'

const people = [
  { id: 1, name: 'Durward Reynolds', unavailable: false },
  { id: 2, name: 'Kenton Towne', unavailable: false },
  { id: 3, name: 'Therese Wunsch', unavailable: false },
  { id: 4, name: 'Benedict Kessler', unavailable: true },
  { id: 5, name: 'Katelyn Rohan', unavailable: false },
]

function MyListbox() {
  const [selectedPerson, setSelectedPerson] = useState(people[0])

  return (
    <Listbox value={selectedPerson} onChange={setSelectedPerson}>
      <Listbox.Button>{selectedPerson.name}</Listbox.Button>
      <Listbox.Options>
        {people.map((person) => (
          /* Disabled options will be skipped by keyboard navigation. */
          <Listbox.Option
            key={person.id}
            value={person}

            disabled={person.unavailable}
          >
            <span className={person.unavailable ? 'opacity-75' : ''}>
              {person.name}
            </span>
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

若要為下拉清單面板的開啟／關閉加上動畫，請使用提供的 Transition 組件。你只需要將 Listbox.Options 包覆於 <Transition> 中，過場動畫就會自動套用。

import { useState } from 'react'
import { Listbox, Transition } from '@headlessui/react'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]

function MyListbox() {
  const [selectedPerson, setSelectedPerson] = useState(people[0])

  return (
    <Listbox value={selectedPerson} onChange={setSelectedPerson}>
      <Listbox.Button>{selectedPerson.name}</Listbox.Button>

      <Transition
        enter="transition duration-100 ease-out"
        enterFrom="transform scale-95 opacity-0"
        enterTo="transform scale-100 opacity-100"
        leave="transition duration-75 ease-out"
        leaveFrom="transform scale-100 opacity-100"
        leaveTo="transform scale-95 opacity-0"
      >
        <Listbox.Options>
          {people.map((person) => (
            <Listbox.Option key={person.id} value={person}>
              {person.name}
            </Listbox.Option>
          ))}
        </Listbox.Options>

      </Transition>
    </Listbox>
  )
}

預設情況下，我們的內建 Transition 組件會自動與 Listbox 組件通訊，以處理開啟／關閉狀態。但是，如果你需要對這些行為有更多的控制權，你可以自行明確地控制它

import { useState } from 'react'
import { Listbox, Transition } from '@headlessui/react'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]

function MyListbox() {
  const [selectedPerson, setSelectedPerson] = useState(people[0])

  return (
    <Listbox value={selectedPerson} onChange={setSelectedPerson}>

      {({ open }) => (
        <>
          <Listbox.Button>{selectedPerson.name}</Listbox.Button>
          {/*
            Use the `Transition` + `open` render prop argument to add transitions.
          */}
          <Transition

            show={open}
            enter="transition duration-100 ease-out"
            enterFrom="transform scale-95 opacity-0"
            enterTo="transform scale-100 opacity-100"
            leave="transition duration-75 ease-out"
            leaveFrom="transform scale-100 opacity-100"
            leaveTo="transform scale-95 opacity-0"
          >
            {/*
              Don't forget to add `static` to your `Listbox.Options`!
            */}

            <Listbox.Options static>
              {people.map((person) => (
                <Listbox.Option key={person.id} value={person}>
                  {person.name}
                </Listbox.Option>
              ))}
            </Listbox.Options>
          </Transition>

        </>
      )}
    </Listbox>
  )
}

由於 Headless UI 組件是無渲染的，因此也能與 React 生態系統中其他動畫函式庫，例如 Framer Motion 和 React Spring，良好地組合運用。

預設的情況下，Listbox 與其子組件各自會渲染一個對應於該組件適當預設的元素。

例如，Listbox.Label 預設會呈現一個 label、Listbox.Button 會呈現一個 button、Listbox.Options 會呈現一個 ul，而 Listbox.Option 會呈現一個 li。相較之下，Listbox 不會渲染元素，而是直接呈現其子元素。

使用 as 道具將組件呈現為不同的元素，或作為你自己的自訂組件，確保你的自訂組件會 轉傳 ref，以便 Headless UI 能正確地建立連結。

import { forwardRef, useState } from 'react'
import { Listbox } from '@headlessui/react'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]


let MyCustomButton = forwardRef(function (props, ref) {
  return <button className="..." ref={ref} {...props} />
})

function MyListbox() {
  const [selectedPerson, setSelectedPerson] = useState(people[0])

  return (

    <Listbox as="div" value={selectedPerson} onChange={setSelectedPerson}>
      <Listbox.Button as={MyCustomButton}>
        {selectedPerson.name}
      </Listbox.Button>


      <Listbox.Options as="div">
        {people.map((person) => (

          <Listbox.Option as="span" key={person.id} value={person}>
            {person.name}
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

若要指示元素直接呈現其子元素而不加包覆元素，請使用 Fragment。

import { useState, Fragment } from 'react'
import { Listbox } from '@headlessui/react'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]

function MyListbox() {
  const [selectedPerson, setSelectedPerson] = useState(people[0])

  return (
    <Listbox value={selectedPerson} onChange={setSelectedPerson}>
      {/* Render a `Fragment` instead of a `button` */}

      <Listbox.Button as={Fragment}>
        <button>{selectedPerson.name}</button>
      </Listbox.Button>
      <Listbox.Options>
        {people.map((person) => (
          <Listbox.Option key={person.id} value={person}>
            {person.name}
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

如果你已將 Listbox.Options 設定橫向顯示樣式，請在 Listbox 組件上使用 horizontal 道具，以使用左右箭頭鍵而非上下箭頭鍵瀏覽項目，並更新輔助技術的 aria-orientation 屬性。

import { useState, Fragment } from 'react'
import { Listbox } from '@headlessui/react'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]

function MyListbox() {
  const [selectedPerson, setSelectedPerson] = useState(people[0])

  return (

    <Listbox value={selectedPerson} onChange={setSelectedPerson} horizontal>
      <Listbox.Button>{selectedPerson.name}</Listbox.Button>
      <Listbox.Options className="flex flex-row">
        {people.map((person) => (
          <Listbox.Option key={person.id} value={person}>
            {person.name}
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

當 Listbox 被切換開啟時，Listbox.Options 會收到焦點。焦點會停留在項目清單中，直到按下 Esc 或使用者點選選項外的範圍。關閉 Listbox 會將焦點返回至 Listbox.Button。

點選 Listbox.Button 會切換選項清單開或關。點選選項清單範圍外的任意位置會關閉 Listbox。

指令描述

Enter, Space, ArrowDown, 或ArrowUp當 Listbox.Button 取得焦點時

開啟 Listbox 並聚焦於已選項目

Esc，當 Listbox 開啟時

關閉 Listbox

ArrowDown或ArrowUp當 Listbox 開啟時

聚焦於上一個/下一個未停用的項目

向左箭頭或向右箭頭當列表方塊開啟且
水平已設定時

聚焦於上一個/下一個未停用的項目

首頁或向上分頁當列表方塊開啟時

聚焦第一個非停用的項目

結尾或向下分頁當列表方塊開啟時

聚焦最後一個非停用的項目

Enter或Space當列表方塊開啟時

選取目前的項目

A–Z或a–z當列表方塊開啟時

聚焦第一個與鍵盤輸入相符的項目

所有相關的 ARIA 屬性會自動管理。

主要的列表方塊元件。

屬性預設值描述
as片段
字串 | 元件

Listbox 應呈現為的元素或元件。

disabledfalse
布林值

使用此屬性停用整個列表方塊元件及相關子項目

value—
T

已選取的值。

defaultValue—
T

使用做為非受控元件時的預設值。

by—
keyof T | ((a: T, z: T) => boolean)

使用此屬性根據特定欄位比較物件，或傳遞您自己的比較功能以完全控制如何比較物件。

onChange—
(value: T) => void

當選取新選項時會呼叫此函式。

水平false
布林值

為 True 時，Listbox.Options 的方向會是 horizontal，否則會是 vertical。

name—
字串

在表單中使用此元件時使用的名稱。

multiplefalse
布林值

是否允許選取多個選項。

Render Prop描述
value

T

已選取的值。

open

布林值

Listbox 是否開啟。

disabled

布林值

Listbox 是否已停用。

Listbox 的按鈕。

屬性預設值描述
asbutton
字串 | 元件

Listbox.Button 應呈示為的元素或元件。

Render Prop描述
value

T

已選取的值。

open

布林值

Listbox 是否開啟。

disabled

布林值

Listbox 是否已停用。

一個可用於更進一步控制 Listbox 會對螢幕朗讀程式宣布文字的標籤。其 id 屬性會自動產生，並透過 aria-labelledby 屬性連結到根 Listbox 元件。

屬性預設值描述
aslabel
字串 | 元件

Listbox.Label 應呈示為的元素或元件。

Render Prop描述
open

布林值

Listbox 是否開啟。

disabled

布林值

Listbox 是否已停用。

直接包覆自訂 Listbox 中選項清單的元件。

屬性預設值描述
asul
字串 | 元件

Listbox.Options 應呈示為的元素或元件。

staticfalse
布林值

元素是否應略過內部管理的開啟/關閉狀態。

注意：無法同時使用 static 和 unmount。如果嘗試執行，會收到 TypeScript 錯誤。

unmounttrue
布林值

元素是否應根據開啟/關閉狀態解除安裝或隱藏。

注意：無法同時使用 static 和 unmount。如果嘗試執行，會收到 TypeScript 錯誤。

Render Prop描述
open

布林值

Listbox 是否開啟。

用於包覆 Listbox 內的每個項目。

屬性預設值描述
value—
T

選項值。

asli
字串 | 元件

Listbox.Option 應呈示為的元素或元件。

disabledfalse
布林值

選項是否應停用於鍵盤導覽和 ARIA 用途。

Render Prop描述
active

布林值

選項是否為目前使用或焦點所在的選項。

selected

布林值

選項是否為已選取的選項。

disabled

布林值

選項是否已停用於鍵盤導覽和 ARIA 用途。

如果你有興趣使用 Headless UI 和 Tailwind CSS 的預先設計元件範例，請查看 Tailwind UI — 由我們打造的漂亮設計和專業製作元件集合。

這是支持我們對此類開源專案進行工作的好方法，使我們能夠改進產品並維護良好狀態。

探索更多預先設計範例→