Preview Updated 2026-05-10

Select

Dropdown picker — array-style options API with clearable, keyboard navigation, and disabled items.

Basic usage

Pass an options array; each item needs at least value and label.

已选：shanghai

<script setup lang="ts">
import { ref } from 'vue';
import { CfSelect, type SelectOption } from '@chufix-design/vue';

const options: SelectOption[] = [
{ value: 'beijing', label: 'Beijing' },
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'guangzhou', label: 'Guangzhou' },
];

const city = ref<string | null>('shanghai');
</script>

<template>
<CfSelect v-model="city" :options="options" placeholder="Pick a city" />
</template>

import { useState } from 'react';
import { CfSelect, type SelectOption } from '@chufix-design/react';

const options: SelectOption[] = [
{ value: 'beijing', label: 'Beijing' },
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'guangzhou', label: 'Guangzhou' },
];

export default function Demo() {
const [city, setCity] = useState<string | null>('shanghai');
return (
  <CfSelect
    value={city}
    options={options}
    placeholder="Pick a city"
    onChange={(v) => setCity(v as string | null)}
  />
);
}

Variants

Three variants matching Input: outline (default) / filled / ghost.

<CfSelect v-model="v1" :options="options" variant="outline" />
<CfSelect v-model="v2" :options="options" variant="filled" />
<CfSelect v-model="v3" :options="options" variant="ghost" />

<CfSelect value={v1} options={options} variant="outline" onChange={setV1} />
<CfSelect value={v2} options={options} variant="filled" onChange={setV2} />
<CfSelect value={v3} options={options} variant="ghost" onChange={setV3} />

States and clearable

clearable shows × when a value is selected; disabled disables the whole control; error switches the border to the error color. Individual options can have disabled: true to be skipped.

<CfSelect v-model="a" :options="options" placeholder="Clearable" clearable />
<CfSelect v-model="b" :options="options" placeholder="Disabled" disabled />
<CfSelect v-model="b" :options="options" placeholder="Error state" error />

<CfSelect value={a} options={options} clearable onChange={setA} />
<CfSelect value={b} options={options} disabled />
<CfSelect value={b} options={options} error />

Events and forms

Beyond value changes, Select exposes events for open state, active option, clear, and focus. When you pass name, it syncs a hidden input so the current value is submitted with native forms.

api

等待交互：打开菜单、移动 active、选择或清空。

<CfSelect
v-model="value"
:options="options"
clearable
name="status"
@change="(value, meta) => console.log(value, meta.option)"
@select="(option) => console.log('select', option)"
@clear="() => console.log('clear')"
@open-change="(open) => console.log('open', open)"
@active-change="(option, index) => console.log(option, index)"
/>

<CfSelect
value={value}
options={options}
clearable
name="status"
onChange={(value, meta) => console.log(value, meta.option)}
onSelect={(option) => console.log('select', option)}
onClear={() => console.log('clear')}
onOpenChange={(open) => console.log('open', open)}
onActiveChange={(option, index) => console.log(option, index)}
/>

Keyboard interaction

Key	Behavior
`↓` / `↑`	Open the menu / move active among options
`Enter` / `Space`	Open the menu / select the active option
`Esc`	Close the menu
`Tab`	Close the menu and return focus to the browser

API

Prop	Type	Default	Description
`options`	`SelectOption[]`	`[]`	Option array, `{ value, label, disabled? }`
`placeholder`	`string`	`'Select'`	Shown when no value is selected
`variant`	`'outline' \| 'filled' \| 'ghost'`	`'outline'`	Visual variant
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Overall size
`clearable`	`boolean`	`false`	Show clear button when a value is selected
`disabled`	`boolean`	`false`	Disable the whole control
`error`	`boolean`	`false`	Error state
`name`	`string`	—	Renders a hidden input for native form submit
`id`	`string`	—	Trigger button id, also wires up the listbox

Events

Vue event	React callback	payload	Description
`change`	`onChange`	`(value, { option })`	Value changed; on clear, `option` is `null`
`select`	`onSelect`	`option`	An option was selected
`clear`	`onClear`	—	Clear button clicked
`open-change`	`onOpenChange`	`open`	Menu opened / closed
`active-change`	`onActiveChange`	`(option, index)`	Keyboard or mouse moved the active option
`focus` / `blur`	`onFocus` / `onBlur`	`FocusEvent`	Trigger button focus events

The current implementation uses an position: absolute overlay. If a parent has overflow: hidden and crops the menu, a Portal version will be added later.