Combobox
Text input with an adjoining button and an expandable menu of options.
TextInput props apply
This component contains a TextInput component. You can bind TextInput props to this component and they will be passed to the TextInput within.
Attributes passed to input
This component will pass any HTML attributes applied to it, except for CSS class, to the <input> element within the component.
Demos
Basic Usage
The Combobox component combines a menu of selectable options with a text box that can accept arbitrary input from the user. The component should receive a v-model binding from its parent as well as an array of options (which can be empty).
<template>
<div>
<cdx-combobox
v-model="selection"
:options="options"
placeholder="Type or choose an option"
/>
<p>
The current value is {{ selection }}
</p>
</div>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxCombobox } from 'vue-components/src/lib';
import { MenuOption } from 'vue-components/src/types';
const options: MenuOption[] = [
{ label: 'a', value: 'a' },
{ label: 'b', value: 'b' },
{ label: 'c', value: 'c' }
];
export default defineComponent( {
name: 'ComboBoxBasic',
components: { CdxCombobox },
data() {
return {
options: options,
selection: ''
};
}
} );
</script>
Clearable, with start icon
Valid TextInput props like startIcon, endIcon, and clearable will be passed on to the embedded TextInput.
<template>
<div>
<cdx-combobox
v-model="selection"
:options="options"
placeholder="Type or choose an option"
:start-icon="icon"
:clearable="true"
/>
<p>
The current value is {{ selection }}
</p>
</div>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxCombobox } from 'vue-components/src/lib';
import { MenuOption } from 'vue-components/src/types';
import { cdxIconSearch } from 'icons';
const options: MenuOption[] = [
{ label: 'a', value: 'a' },
{ label: 'b', value: 'b' },
{ label: 'c', value: 'c' }
];
export default defineComponent( {
name: 'ComboBoxClearableStartIcon',
components: { CdxCombobox },
data() {
return {
options: options,
selection: '',
icon: cdxIconSearch
};
}
} );
</script>
Like other menu-style components (Select, Lookup, etc.), a custom option template can be provided via the #menu-option slot.
<template>
<div>
<cdx-combobox
v-model="selection"
:options="options"
placeholder="Type or choose an option"
>
<template #menu-option="{ option }">
<cdx-icon v-if="option.icon" :icon="option.icon" />
</template>
</cdx-combobox>
<p>
The current value is {{ selection }}
</p>
</div>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxCombobox, CdxIcon } from 'vue-components/src/lib';
import { MenuOption } from 'vue-components/src/types';
import { cdxIconCamera, cdxIconBook, cdxIconClock } from 'icons';
const options: MenuOption[] = [
{ value: 'camera', icon: cdxIconCamera },
{ value: 'book', icon: cdxIconBook },
{ value: 'clock', icon: cdxIconClock }
];
export default defineComponent( {
name: 'ComboboxCustomOption',
components: { CdxCombobox, CdxIcon },
data() {
return {
options: options,
selection: ''
};
}
} );
</script>
A non-clickable footer can be added to the end of the options menu via the #footer slot.
<template>
<div>
<cdx-combobox
v-model="selection"
:options="options"
placeholder="Type or choose an option"
>
<template v-if="options.length < 1" #footer>
Sorry, no options to display.
</template>
</cdx-combobox>
<p>
The current value is {{ selection }}
</p>
</div>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxCombobox } from 'vue-components/src/lib';
import { MenuOption } from 'vue-components/src/types';
const options: MenuOption[] = [];
export default defineComponent( {
name: 'ComboboxNoResults',
components: { CdxCombobox },
data() {
return {
options: options,
selection: ''
};
}
} );
</script>
Usage
Props
| Prop name | Description | Type | Values | Default |
|---|
| options | Menu options. See the MenuOption type. | MenuOption[] | - | |
| modelValue | Value provided by v-model binding in the parent component. | string|number | - | '' |
| disabled | Whether the dropdown is disabled. | boolean | - | false |
Events
| Event name | Properties | Description |
|---|
| update:modelValue | value string | number - The new value | When the selection value changes. |
Slots
| Name | Description | Bindings |
|---|
| menu-option | Display of an individual option in the menu | option MenuOption - The current option |
| footer | Content to display at the end of the options list | |