开发预览更新于 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' },
  { value: 'angular', label: 'Angular' },
  { value: 'qwik', label: 'Qwik' },
];
</script>

<template>
  <div style="display:flex; gap: 12px; align-items: flex-start;">
    <CfCombobox v-model="value" :options="options" clearable />
    <span style="font-size: 12px; color: var(--fg-3); align-self: center;">
      当前：{{ value ?? '(无)' }}
    </span>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { CfCombobox } from '@chufix-design/vue';

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

<template>
  <div style="display:flex; gap: 12px; align-items: flex-start;">
    <CfCombobox v-model="value" :options="options" clearable />
    <span style="font-size: 12px; color: var(--fg-3); align-self: center;">
      当前：{{ value ?? '(无)' }}
    </span>
  </div>
</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} />;
}

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

const options= [
{ 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: '后端' },
  { value: 'devops', label: '运维' },
]);

function onCreate(v: string) {
  options.value.push({ value: v.toLowerCase(), label: v });
}
</script>

<template>
  <CfCombobox
    v-model="value"
    :options="options"
    allow-create
    clearable
    placeholder="选择或新增分类"
    @create="onCreate"
  />
</template>

<script setup>
import { ref } from 'vue';
import { CfCombobox } from '@chufix-design/vue';

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

function onCreate(v) {
  options.value.push({ value: v.toLowerCase(), label: v });
}
</script>

<template>
  <CfCombobox
    v-model="value"
    :options="options"
    allow-create
    clearable
    placeholder="选择或新增分类"
    @create="onCreate"
  />
</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 }])
    }
  />
);
}

import { useState } from 'react';
import { CfCombobox } 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 }])
    }
  />
);
}

尺寸

背景

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

const a = ref<string | number | null>(null);
const b = ref<string | number | null>(null);
const c = ref<string | number | null>(null);
const options: ComboboxOption[] = [
  { value: 'apple', label: 'Apple' },
  { value: 'banana', label: 'Banana' },
  { value: 'cherry', label: 'Cherry' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 8px; max-width: 320px;">
    <CfCombobox v-model="a" :options="options" size="sm" placeholder="sm" />
    <CfCombobox v-model="b" :options="options" size="md" placeholder="md" />
    <CfCombobox v-model="c" :options="options" size="lg" placeholder="lg" />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { CfCombobox } from '@chufix-design/vue';

const a = ref<string | number | null>(null);
const b = ref<string | number | null>(null);
const c = ref<string | number | null>(null);
const options= [
  { value: 'apple', label: 'Apple' },
  { value: 'banana', label: 'Banana' },
  { value: 'cherry', label: 'Cherry' },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 8px; max-width: 320px;">
    <CfCombobox v-model="a" :options="options" size="sm" placeholder="sm" />
    <CfCombobox v-model="b" :options="options" size="md" placeholder="md" />
    <CfCombobox v-model="c" :options="options" size="lg" placeholder="lg" />
  </div>
</template>

<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）。