AI 模型選擇器｜免費 React 元件

AI 應用的模型切換下拉選單：每個選項列出提供者色塊、智力星級、速度閃電與成本 $ 徽章，可標示「推薦」籤，選中項打勾、面板以 spring 開合，並支援完整鍵盤操作。

把這個效果裝進你的專案

在專案資料夾執行指令，CLI 會加入原始碼與依賴套件，再依下方使用範例引用元件。

npx webberui@latest add ai-model-picker

還沒有專案，或安裝遇到問題？看快速開始 →

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

預設選取defaultValue

提示文字placeholder

面板最大高度maxHeight

280

hover 預覽卡preview

清單底部漸隱scrollFade

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

編輯中的呼叫預設屬性

<AiModelPicker/>

    </div>
  );
}

完整範例包含預覽的排版與資料。先安裝元件，再把範例檔貼入你的專案。

安裝

npx webberui@latest add https://webberui.com/r/ai-model-picker.json

或在 components.json 設定 registries 後，改用 @webberui/ai-model-picker 安裝。

使用

import { AiModelPicker, type AiModel } from "@/components/ui/ai-model-picker";

const models: AiModel[] = [
  {
    id: "aurora-pro",
    name: "Aurora Pro",
    provider: "Auralab",
    intelligence: 4,
    speed: 2,
    cost: 2,
    recommended: true,
    description: "智力與速度的最佳平衡",
  },
  {
    id: "swift-mini",
    name: "Swift Mini",
    provider: "Swiftware",
    intelligence: 3,
    speed: 3,
    cost: 1,
  },
];

<AiModelPicker
  models={models}
  defaultValue="aurora-pro"
  onChange={(model) => console.log(model.id)}
/>

預覽卡與推理設定

開啟 preview 後，hover 或用方向鍵反白某個選項時，面板右側會出現預覽卡：智力、速度、上下文、成本四條指標，以及推理強度（低／中／高）與速度模式（標準／快速）兩組單選。切換設定時指標即時位移，淡色底線標出原始值，方便比較推移方向；與預設（中、標準）不同的設定會以徽章顯示在觸發鈕上。scrollFade 則在清單還能往下捲時於底部加上漸隱遮罩。

const [options, setOptions] = React.useState<AiModelOptions>({
  effort: "medium",
  speed: "standard",
});

<AiModelPicker
  models={models}
  defaultValue="aurora-pro"
  preview
  scrollFade
  options={options}
  onOptionsChange={setOptions}
/>

context（1–5）與 contextLabel 是 AiModel 的選用欄位，只用於預覽卡的「上下文」指標；未提供時以 3 計。兩個新功能預設都關閉，不開啟時面板外觀與行為與先前版本相同。

Props

Prop	型別	預設值	說明
`models`	`AiModel[]`	—	可選擇的模型清單
`value`	`string`	—	受控模式：目前選中的模型 id
`defaultValue`	`string`	—	非受控模式：預設選中的模型 id
`onChange`	`(model: AiModel) => void`	—	選擇變更時回呼，帶入完整模型物件
`placeholder`	`string`	`"選擇模型"`	尚未選擇任何模型時，觸發鈕顯示的文字
`maxHeight`	`number`	`280`	下拉面板的最大高度（px），超出時面板內部捲動
`preview`	`boolean`	`false`	hover 或鍵盤反白項目時，於面板右側顯示預覽卡（四條指標與設定）
`options`	`AiModelOptions`	—	受控模式：推理強度與速度模式設定
`defaultOptions`	`AiModelOptions`	`{ effort: "medium", speed: "standard" }`	非受控模式：初始設定
`onOptionsChange`	`(options: AiModelOptions) => void`	—	預覽卡內設定變更時回呼
`scrollFade`	`boolean`	`false`	清單還能捲動時，在底部顯示漸隱遮罩
`className`	`string`	—	透傳到最外層容器，經 cn() 合併

AiModel

欄位	型別	預設值	說明
`id`	`string`	—	唯一識別碼，作為選擇值使用
`name`	`string`	—	模型顯示名稱
`provider`	`string`	—	提供者名稱，顯示於名稱下方並用於色塊配色
`hue`	`number`	依 provider 推導	提供者色塊的色相（0–360）
`intelligence`	`number`	—	智力星級（1–5，以星星呈現）
`speed`	`number`	—	速度等級（1–3，以閃電呈現）
`cost`	`number`	—	成本等級（1–3，以 $ 呈現）
`description`	`string`	—	一行簡短描述，顯示於選項列
`recommended`	`boolean`	`false`	是否顯示「推薦」籤
`context`	`number`	`3`	上下文長度等級（1–5），用於預覽卡的「上下文」指標
`contextLabel`	`string`	—	上下文長度的顯示文字（例如「128K」），顯示於指標旁

AiModelOptions

欄位	型別	預設值	說明
`effort`	`"low" \| "medium" \| "high"`	`"medium"`	推理強度：low 提高速度、降低成本與智力；high 反之
`speed`	`"standard" \| "fast"`	`"standard"`	速度模式：fast 提高速度與成本

可及性

觸發鈕標記 aria-haspopup="listbox" 與 aria-expanded，面板為 role="listbox"；開啟後焦點移入面板，關閉時焦點回到觸發鈕
完整鍵盤支援：↑/↓ 開啟並移動反白、Home/End 跳至首尾、Enter/Space 選取、Esc 關閉、Tab 收合離開
aria-activedescendant 指向目前反白選項，選中項標記 aria-selected，輔助科技可正確朗讀
星級與徽章以 role="img" 搭配「智力 4/5」等文字標籤朗讀，個別圖示對輔助科技隱藏（aria-hidden）
預覽卡為具名的 aside，四條指標以 role="meter" 搭配 aria-valuenow 朗讀；推理強度與速度模式是 role="radiogroup"，方向鍵切換並立即套用
開啟 preview 時 Tab 會從清單移到預覽卡的設定，焦點離開整個元件才收合；在預覽卡內按 Esc 一樣會關閉並把焦點還給觸發鈕
使用者系統開啟「減少動態效果」時，面板退化為單純淡入淡出，箭頭與打勾不做彈跳動畫，指標長條直接跳到新值不做過渡

AI 模型選擇器

把這個效果裝進你的專案

本頁目錄