Skies.ui
元件 (Components)

Select 選取

Skies.ui Select:Radix 下拉選單,鍵盤與螢幕閱讀器友善,與表單、主題對齊;API 與範例。

Select 選取

SelectRadix Select 組合而成:SelectTrigger + SelectValue 顯示目前選項,SelectContent 內放 SelectItem。樣式與 border-inputbg-cardfocus:ring-ring 等語意一致。

基本用法

import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@skies-ui/ui";

export function AirportSelect() {
  return (
    <Select defaultValue="tpe">
      <SelectTrigger aria-label="選擇機場">
        <SelectValue placeholder="選擇機場" />
      </SelectTrigger>
      <SelectContent>
        <SelectItem value="tpe">台北 TPE</SelectItem>
        <SelectItem value="khh">高雄 KHH</SelectItem>
        <SelectItem value="rmq">台中 RMQ</SelectItem>
      </SelectContent>
    </Select>
  );
}

未包在表單裡、又沒有外層文字標籤時,請在 SelectTrigger 加上 aria-label(或 aria-labelledby)。

群組與分隔線

使用 SelectGroupSelectLabelSelectSeparator 整理長清單。

<Select defaultValue="react">
  <SelectTrigger aria-label="選擇框架">
    <SelectValue placeholder="選擇框架" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel>前端</SelectLabel>
      <SelectItem value="react">React</SelectItem>
      <SelectItem value="vue">Vue</SelectItem>
    </SelectGroup>
    <SelectSeparator />
    <SelectGroup>
      <SelectLabel>後端</SelectLabel>
      <SelectItem value="node">Node</SelectItem>
      <SelectItem value="bun">Bun</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>

停用選項

SelectItem 上使用 disabled

受控與表單

  • 非受控defaultValue 搭配 onValueChange
  • 受控value + onValueChange
  • 放在 <form> 內時,在 Select 上設定 name(Radix 會渲染隱藏欄位提交值)。

ButtonCard 並用時,表單送出鈕請使用 type="submit"Button

API 摘要

元件說明
Select根節點;value / defaultValue / onValueChange / name / disabled
SelectTrigger對應 Radix Trigger;內含圖示與 SelectValue
SelectValue顯示選中文字;placeholder
SelectContent浮層內容;可傳 position(預設 popper)、sideOffset
SelectItem單一選項;value、可選 disabled
SelectGroup / SelectLabel / SelectSeparator分組與視覺分隔
SelectScrollUpButton / SelectScrollDownButton長清單捲動(已內建在 SelectContent 內)

套件為 Client Component(檔案含 "use client"),請在 App Router 中由 Client 邊界或 MDX 使用。

On this page