开发预览更新于 2026-05-10

Combobox 组合选择

Select 的可输入变体，键入即过滤选项，可选择允许新增条目。

基础用法

把 options 传进去，v-model 绑定当前值。点开后可以直接输入过滤；↑↓ 移动，Enter 选中，Esc 收起。

当前：vue

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

const value = ref<string | number | null>('vue');
const options: ComboboxOption[] = [
{ value: 'vue', label: 'Vue 3' },
{ value: 'react', label: 'React 18' },
{ value: 'svelte', label: 'Svelte 5' },
{ value: 'solid', label: 'SolidJS' },
];
</script>

<template>
<CfCombobox v-model="value" :options="options" clearable />
</template>

import { useState } from 'react';
import { CfCombobox, type ComboboxOption } from '@chufix-design/react';

const options: ComboboxOption[] = [
{ value: 'vue', label: 'Vue 3' },
{ value: 'react', label: 'React 18' },
{ value: 'svelte', label: 'Svelte 5' },
{ value: 'solid', label: 'SolidJS' },
];

export default function Demo() {
const [value, setValue] = useState<string | number | null>('vue');
return <CfCombobox value={value} options={options} clearable onChange={setValue} />;
}

允许新增

allow-create 打开后，输入未匹配的内容时菜单底部会出现「创建 “xxx”」一项；按 Enter 或点击它都能把当前输入作为新值提交。@create（Vue）/ onCreate（React）会同时回调。

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

const value = ref<string | number | null>(null);
const options = ref<ComboboxOption[]>([
{ value: 'frontend', label: '前端' },
{ value: 'backend', label: '后端' },
]);
</script>

<template>
<CfCombobox
  v-model="value"
  :options="options"
  allow-create
  clearable
  @create="(v) => options.push({ value: v.toLowerCase(), label: v })"
/>
</template>

import { useState } from 'react';
import { CfCombobox, type ComboboxOption } from '@chufix-design/react';

export default function Demo() {
const [value, setValue] = useState<string | number | null>(null);
const [options, setOptions] = useState<ComboboxOption[]>([
  { value: 'frontend', label: '前端' },
  { value: 'backend', label: '后端' },
]);
return (
  <CfCombobox
    value={value}
    options={options}
    allowCreate
    clearable
    onChange={setValue}
    onCreate={(v) =>
      setOptions((arr) => [...arr, { value: v.toLowerCase(), label: v }])
    }
  />
);
}

尺寸

<CfCombobox size="sm" :options="options" />
<CfCombobox size="md" :options="options" />
<CfCombobox size="lg" :options="options" />

<CfCombobox size="sm" options={options} />
<CfCombobox size="md" options={options} />
<CfCombobox size="lg" options={options} />

API

属性	类型	默认值	说明
`modelValue` (Vue) / `value` (React)	`string \| number \| null`	`null`	当前值
`options`	`ComboboxOption[]`	`[]`	`{ value, label, disabled? }` 列表
`placeholder`	`string`	`'请选择或输入'`	占位文案
`variant`	`'outline' \| 'filled' \| 'ghost'`	`'outline'`	视觉模式
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	尺寸
`disabled`	`boolean`	`false`	禁用
`clearable`	`boolean`	`false`	显示清除按钮
`error`	`boolean`	`false`	错误态
`allowCreate`	`boolean`	`false`	是否允许把输入作为新值提交
`filter`	`(query, option) => boolean`	默认按 label 与 value 子串匹配	自定义过滤函数
`emptyText`	`string`	`'无匹配项'`	无结果时的占位文字

事件：update:modelValue / change / create（React 端：onChange / onCreate）。