Combobox lets you choose a single or multiple values from a list of options.
<tk-combobox name="basic-combobox"></tk-combobox>
<script>
const basicCombobox = document.querySelector('tk-combobox[name="basic-combobox"]');
basicCombobox.options = [{
label: 'The Phantom Menace',
value: '8515e363-c3c6-4b30-a38e-53c2d0c890d7',
}, {
label: 'Attack of the Clones',
value: 'd4e855ed-2376-4b97-b6e3-0b6e9507fa20',
}, {
label: 'Revenge of the Sith',
value: '0ed4076d-0ba5-4694-b2f3-fcd3c26ea321',
}, {
label: 'A New Hope',
value: '702ba197-dbd0-4983-8e36-d60680eb5a68',
}, {
label: 'The Empire Strikes Back',
value: '7a0386b9-555c-47fd-80b9-9bb8ad25e150',
}, {
label: 'Return of the Jedi',
value: '5f3b9958-6682-4b68-81f1-5812813a01e2',
}, {
label: 'The Force Awakens',
value: '46295138-9b6d-4493-a4e0-e125d93977b9',
}, {
label: 'The Last Jedi',
value: '4f9b656f-58f9-4033-9c84-5e53455e350b',
}, {
label: 'The Rise of Skywalker',
value: 'bf37ad10-1924-4f14-bc9f-96561350a697',
}];
</script><tk-combobox name="method-combobox"></tk-combobox>
<script>
(async () => {
await customElements.whenDefined('tk-combobox');
const methodCombobox = document.querySelector('tk-combobox[name="method-combobox"]');
await methodCombobox.setOptions([{
label: 'The Phantom Menace',
value: 'sw1',
}, {
label: 'Attack of the Clones',
value: 'sw2',
}, {
label: 'Revenge of the Sith',
value: 'sw3',
}, {
label: 'A New Hope',
value: 'sw4',
}, {
label: 'The Empire Strikes Back',
value: 'sw5',
}, {
label: 'Return of the Jedi',
value: 'sw6',
}, {
label: 'The Force Awakens',
value: 'sw7',
}, {
label: 'The Last Jedi',
value: 'sw8',
}, {
label: 'The Rise of Skywalker',
value: 'sw9',
}]);
})()
</script>You can use the setOptions method to set the options of the combobox. Note: You should ensure that the component is defined by using the customElements.whenDefined method before attempting to call public methods.
<tk-combobox name="sublabels-combobox"></tk-combobox>
<script>
const sublabelsCombobox = document.querySelector('tk-combobox[name="sublabels-combobox"]');
sublabelsCombobox.options = [{
label: 'The Phantom Menace',
subLabel: 'Darth Maul movie',
value: 'sw1',
icon: 'wrench',
}, {
label: 'Attack of the Clones',
subLabel: 'A lot of clones',
value: 'sw2',
icon: 'audience',
}, {
label: 'Revenge of the Sith',
subLabel: 'Oh, Palpatine is the villain...',
value: 'sw3',
icon: 'frustration',
}, {
label: 'A New Hope',
subLabel: 'Who is Darth Vader???',
value: 'sw4',
icon: 'eye',
}, {
label: 'The Empire Strikes Back',
subLabel: 'WAT!? Darth Vader is the father????',
value: 'sw5',
icon: 'detach-link',
}, {
label: 'Return of the Jedi',
subLabel: 'Poor Yoda...',
value: 'sw6',
icon: 'gizmo',
}, {
label: 'The Force Awakens',
subLabel: 'Cool mask, Kylo',
value: 'sw7',
icon: 'desktop',
}, {
label: 'The Last Jedi',
subLabel: 'You are very old, Luke',
value: 'sw8',
icon: 'atom',
}, {
label: 'The Rise of Skywalker',
subLabel: 'More clones...',
value: 'sw9',
icon: 'delete',
}];
</script>You can add more information to the options using the icon and subLabel attributes.
<tk-combobox name="pictograms-combobox"></tk-combobox>
<script>
const pictogramsCombobox = document.querySelector('tk-combobox[name="pictograms-combobox"]');
const pictogramsComboboxOptions = [{
label: 'How often do you shop online?',
value: 'sw1',
pictogram: 'rating',
}, {
label: 'How comfortable are you buying online?',
value: 'sw2',
pictogram: 'written-response',
}, {
label: 'Thank you for taking the time to buy online',
value: 'sw3',
pictogram: 'multiple-choice',
}, {
label: "Anything else you'd like to add?",
value: 'sw4',
pictogram: 'instructions',
}, {
label: 'Thank you for taking the time to buy online',
value: 'sw5',
pictogram: 'multiple-choice',
}, {
label: "Anything else you'd like to add?",
value: 'sw6',
pictogram: 'instructions',
}, {
label: 'How comfortable are you buying online?',
value: 'sw7',
pictogram: 'written-response',
}, {
label: 'How often do you shop online?',
value: 'sw8',
pictogram: 'rating',
}];
pictogramsCombobox.options = pictogramsComboboxOptions.map(o => {
const { label, value, pictogram } = o;
return {
label: label.length > 35 ? `${label.substring(0, 32)}...` : label,
value,
pictogram
}
});
</script>In addition to icons there’s also support for using pictograms inside combobox options.
<tk-combobox name="size-standard-combobox" size="standard"></tk-combobox>
<tk-combobox name="size-large-combobox" size="large"></tk-combobox>
<script>
const sizeOptions = [{
label: 'The Phantom Menace',
value: 'sw1',
}, {
label: 'Attack of the Clones',
value: 'sw2',
}, {
label: 'Revenge of the Sith',
value: 'sw3',
}, {
label: 'A New Hope',
value: 'sw4',
}, {
label: 'The Empire Strikes Back',
value: 'sw5',
}, {
label: 'Return of the Jedi',
value: 'sw6',
}, {
label: 'The Force Awakens',
value: 'sw7',
}, {
label: 'The Last Jedi',
value: 'sw8',
}, {
label: 'The Rise of Skywalker',
value: 'sw9',
}];
const sizeStandardCombobox = document.querySelector('tk-combobox[name="size-standard-combobox"]');
const sizeLargeCombobox = document.querySelector('tk-combobox[name="size-large-combobox"]');
sizeStandardCombobox.options = sizeOptions;
sizeLargeCombobox.options = sizeOptions;
</script><tk-combobox name="variant-outline-combobox" variant="outline"></tk-combobox>
<tk-combobox name="variant-filled-combobox" variant="filled"></tk-combobox>
<script>
const variantOptions = [{
label: 'The Phantom Menace',
value: 'sw1',
}, {
label: 'Attack of the Clones',
value: 'sw2',
}, {
label: 'Revenge of the Sith',
value: 'sw3',
}, {
label: 'A New Hope',
value: 'sw4',
}, {
label: 'The Empire Strikes Back',
value: 'sw5',
}, {
label: 'Return of the Jedi',
value: 'sw6',
}, {
label: 'The Force Awakens',
value: 'sw7',
}, {
label: 'The Last Jedi',
value: 'sw8',
}, {
label: 'The Rise of Skywalker',
value: 'sw9',
}];
const variantOutlineCombobox = document.querySelector('tk-combobox[name="variant-outline-combobox"]');
const variantFilledCombobox = document.querySelector('tk-combobox[name="variant-filled-combobox"]');
variantOutlineCombobox.options = variantOptions;
variantFilledCombobox.options = variantOptions;
</script><tk-combobox name="invalid-combobox" invalid="true"></tk-combobox>
<script>
const invalidCombobox = document.querySelector('tk-combobox[name="invalid-combobox"]');
invalidCombobox.options = [{
label: 'The Phantom Menace',
value: 'sw1',
}, {
label: 'Attack of the Clones',
value: 'sw2',
}, {
label: 'Revenge of the Sith',
value: 'sw3',
}, {
label: 'A New Hope',
value: 'sw4',
}, {
label: 'The Empire Strikes Back',
value: 'sw5',
}, {
label: 'Return of the Jedi',
value: 'sw6',
}, {
label: 'The Force Awakens',
value: 'sw7',
}, {
label: 'The Last Jedi',
value: 'sw8',
}, {
label: 'The Rise of Skywalker',
value: 'sw9',
}];
</script><tk-combobox name="custom-value-formatter-options-combobox"></tk-combobox>
<script>
const customValueFormatterOptionsCombobox = document.querySelector('tk-combobox[name="custom-value-formatter-options-combobox"]');
customValueFormatterOptionsCombobox.options = [{
label: 'The Phantom Menace',
value: 'sw1',
}, {
label: 'Attack of the Clones',
value: 'sw2',
}, {
label: 'Revenge of the Sith',
value: 'sw3',
}, {
label: 'A New Hope',
value: 'sw4',
}, {
label: 'The Empire Strikes Back',
value: 'sw5',
}, {
label: 'Return of the Jedi',
value: 'sw6',
}, {
label: 'The Force Awakens',
value: 'sw7',
}, {
label: 'The Last Jedi',
value: 'sw8',
}, {
label: 'The Rise of Skywalker',
value: 'sw9',
}];
customValueFormatterOptionsCombobox.selectedValueFormatter = (selectedOption, selectedOptions) => {
const containerElement = document.createElement('div');
const boldSpan = document.createElement('span');
boldSpan.textContent = `Selected ${selectedOptions.length} options: ${selectedOption.value}`;
containerElement.appendChild(boldSpan);
return containerElement;
};
</script>You can customize the label that is being showed when an option is selected with the selected-value-formatter prop. This function provides the selected option item and the array of selected options. This is especially useful for multiple combobox.
<tk-combobox name="custom-value-viewer-options-combobox"></tk-combobox>
<script>
const customValueViewerOptionsCombobox = document.querySelector('tk-combobox[name="custom-value-viewer-options-combobox"]');
customValueViewerOptionsCombobox.options = [{
label: 'The Phantom Menace',
value: 'sw1',
}, {
label: 'Attack of the Clones',
value: 'sw2',
}, {
label: 'Revenge of the Sith',
value: 'sw3',
}, {
label: 'A New Hope',
value: 'sw4',
}, {
label: 'The Empire Strikes Back',
value: 'sw5',
}, {
label: 'Return of the Jedi',
value: 'sw6',
}, {
label: 'The Force Awakens',
value: 'sw7',
}, {
label: 'The Last Jedi',
value: 'sw8',
}, {
label: 'The Rise of Skywalker',
value: 'sw9',
}];
customValueViewerOptionsCombobox.valueViewerFormatter = (selectedOptions) => {
const containerElement = document.createElement('div');
const boldSpan = document.createElement('span');
boldSpan.textContent = `Selected ${selectedOptions.length} of ${customValueViewerOptionsCombobox.options.length} options.`;
containerElement.appendChild(boldSpan);
return containerElement;
};
</script>You can customize the label that is being showed for the selected options with the value-viewer-formatter prop. This function provides the array of selected options. This is especially useful for multiple combobox.
<tk-combobox disabled name="disabled-combobox"></tk-combobox>
<script>
const disabledCombobox = document.querySelector('tk-combobox[name="disabled-combobox"]');
disabledCombobox.options = [{
label: 'The Phantom Menace',
value: 'sw1',
}, {
label: 'Attack of the Clones',
value: 'sw2',
}, {
label: 'Revenge of the Sith',
value: 'sw3',
}, {
label: 'A New Hope',
value: 'sw4',
}, {
label: 'The Empire Strikes Back',
value: 'sw5',
}, {
label: 'Return of the Jedi',
value: 'sw6',
}, {
label: 'The Force Awakens',
value: 'sw7',
}, {
label: 'The Last Jedi',
value: 'sw8',
}, {
label: 'The Rise of Skywalker',
value: 'sw9',
}];
</script>You can set a combobox as disabled using the disabled prop.
<tk-combobox name="default-selected-combobox" default-value="sw2"></tk-combobox>
<script>
const defaultSelectedCombobox = document.querySelector('tk-combobox[name="default-selected-combobox"]');
defaultSelectedCombobox.options = [{
label: 'The Phantom Menace',
value: 'sw1',
}, {
label: 'Attack of the Clones',
value: 'sw2',
}, {
label: 'Revenge of the Sith',
value: 'sw3',
}, {
label: 'A New Hope',
value: 'sw4',
}, {
label: 'The Empire Strikes Back',
value: 'sw5',
}, {
label: 'Return of the Jedi',
value: 'sw6',
}, {
label: 'The Force Awakens',
value: 'sw7',
}, {
label: 'The Last Jedi',
value: 'sw8',
}, {
label: 'The Rise of Skywalker',
value: 'sw9',
}];
</script>In case that you need to set an initial selected option, you can use the defaultValue prop. Note that this will create the tk-combobox as an uncontrolled element.
<tk-combobox name="controlled-combobox" value="sw2"></tk-combobox>
<script>
const controlledCombobox = document.querySelector('tk-combobox[name="controlled-combobox"]');
controlledCombobox.options = [{
label: 'The Phantom Menace',
value: 'sw1',
}, {
label: 'Attack of the Clones',
value: 'sw2',
}, {
label: 'Revenge of the Sith',
value: 'sw3',
}, {
label: 'A New Hope',
value: 'sw4',
}, {
label: 'The Empire Strikes Back',
value: 'sw5',
}, {
label: 'Return of the Jedi',
value: 'sw6',
}, {
label: 'The Force Awakens',
value: 'sw7',
}, {
label: 'The Last Jedi',
value: 'sw8',
}, {
label: 'The Rise of Skywalker',
value: 'sw9',
}];
controlledCombobox.addEventListener('valueChanged', (valueChanged) => {
controlledCombobox.setValue(valueChanged.detail.newValue);
});
</script>You can create a tk-combobox as a controlled element using the value prop and listening the value changes with the valueChanged event. Combobox elements must be either controlled or uncontrolled and you will need to specify either the value prop or the defaultValue prop, but not both.
<tk-combobox name="disabled-options-combobox"></tk-combobox>
<script>
const disabledOptionsCombobox = document.querySelector('tk-combobox[name="disabled-options-combobox"]');
disabledOptionsCombobox.options = [{
label: 'The Phantom Menace',
value: 'sw1',
}, {
label: 'Attack of the Clones',
value: 'sw2',
}, {
label: 'Revenge of the Sith',
value: 'sw3',
disabled: true,
}, {
label: 'A New Hope',
value: 'sw4',
}, {
label: 'The Empire Strikes Back',
value: 'sw5',
}, {
label: 'Return of the Jedi',
value: 'sw6',
}, {
label: 'The Force Awakens',
value: 'sw7',
disabled: true,
}, {
label: 'The Last Jedi',
value: 'sw8',
}, {
label: 'The Rise of Skywalker',
value: 'sw9',
}];
</script>You can use the disabled attribute in the options structure to disable an option.
<tk-combobox name="deactivate-deselection-combobox"></tk-combobox>
<script>
const deactivateDeselectionCombobox = document.querySelector('tk-combobox[name="deactivate-deselection-combobox"]');
deactivateDeselectionCombobox.options = [{
label: 'The Phantom Menace',
value: 'sw1',
}, {
label: 'Attack of the Clones',
value: 'sw2',
deselectable: false,
}, {
label: 'Revenge of the Sith',
value: 'sw3',
}, {
label: 'A New Hope',
value: 'sw4',
}, {
label: 'The Empire Strikes Back',
value: 'sw5',
}, {
label: 'Return of the Jedi',
value: 'sw6',
}, {
label: 'The Force Awakens',
value: 'sw7',
}, {
label: 'The Last Jedi',
value: 'sw8',
}, {
label: 'The Rise of Skywalker',
value: 'sw9',
}];
</script>By default, all the options are deselectable but if you need to avoid this behavior, you can use the deselectable attribute to avoid it.
<tk-combobox name="dividers-combobox"></tk-combobox>
<script>
const dividersCombobox = document.querySelector('tk-combobox[name="dividers-combobox"]');
dividersCombobox.options = [{
label: 'The Phantom Menace',
value: 'sw1',
}, {
label: 'Attack of the Clones',
value: 'sw2',
}, {
label: 'Revenge of the Sith',
value: 'sw3',
}, {
divider: true,
}, {
label: 'A New Hope',
value: 'sw4',
}, {
label: 'The Empire Strikes Back',
value: 'sw5',
}, {
label: 'Return of the Jedi',
value: 'sw6',
}, {
divider: true,
}, {
label: 'The Force Awakens',
value: 'sw7',
}, {
label: 'The Last Jedi',
value: 'sw8',
}, {
label: 'The Rise of Skywalker',
value: 'sw9',
}];
</script>You can create dividers adding a new structure in the options with the divider attribute settled to true.
<tk-combobox name="avoid-close-on-select-combobox" avoid-close-on-select></tk-combobox>
<script>
const avoidCloseOnSelectCombobox = document.querySelector('tk-combobox[name="avoid-close-on-select-combobox"]');
avoidCloseOnSelectCombobox.options = [{
label: 'The Phantom Menace',
value: 'sw1',
}, {
label: 'Attack of the Clones',
value: 'sw2',
}, {
label: 'Revenge of the Sith',
value: 'sw3',
}, {
label: 'A New Hope',
value: 'sw4',
}, {
label: 'The Empire Strikes Back',
value: 'sw5',
}, {
label: 'Return of the Jedi',
value: 'sw6',
}, {
label: 'The Force Awakens',
value: 'sw7',
}, {
label: 'The Last Jedi',
value: 'sw8',
}, {
label: 'The Rise of Skywalker',
value: 'sw9',
}];
</script>By default, the tk-combobox closes the list when an option is selected. To avoid this behavior, you can use the avoid-close-on-select attribute.
<tk-combobox name="multiple-combobox" multiple></tk-combobox>
<script>
const multipleCombobox = document.querySelector('tk-combobox[name="multiple-combobox"]');
multipleCombobox.options = [{
label: 'The Phantom Menace',
value: 'sw1',
}, {
label: 'Attack of the Clones',
value: 'sw2',
}, {
label: 'Revenge of the Sith',
value: 'sw3',
}, {
label: 'A New Hope',
value: 'sw4',
}, {
label: 'The Empire Strikes Back',
value: 'sw5',
}, {
label: 'Return of the Jedi',
value: 'sw6',
}, {
label: 'The Force Awakens',
value: 'sw7',
}, {
label: 'The Last Jedi',
value: 'sw8',
}, {
label: 'The Rise of Skywalker',
value: 'sw9',
}];
</script>If you need to allow the multi selection feature, you can use the multiple attribute. With multiple combobox, the avoid-close-on-select prop is settled to true by default.
Component to render a combobox element.
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
autofocus |
autofocus |
Flag to focus the select on page load. The autofocus prop should not be used, as it can reduce usability and accessibility for users. |
boolean |
false |
avoidCloseOnSelect |
avoid-close-on-select |
Flag to avoid close the combobox list on select an option. In case of multiple=true, this prop will be settled to true. |
boolean |
(() => { if (this.avoidCloseOnSelect) { return this.avoidCloseOnSelect; } return this.multiple; })() |
defaultValue |
default-value |
Default value of the combobox. (uncontrolled field) | string | string[] |
undefined |
disabled |
disabled |
Flag to make the combobox disabled. | boolean |
false |
invalid |
invalid |
Flag to set the combobox as invalid. | boolean |
false |
multiple |
multiple |
Flag to allow multiselection in the combobox. | boolean |
false |
name (required) |
name |
Name of the combobox. | string |
undefined |
options |
– | Options of the combobox. | ComboboxOptionOrDividerType[] |
[] |
selectedValueFormatter |
– | Function to customize how to display each selected value of the combobox. Especially useful for multiple combobox. |
(selectedOption: ComboboxOptionOrDividerType, selectedOptions: string[]) => string | HTMLElement |
DEFAULT_SELECTED_VALUE_FORMATTER |
size |
size |
Size of the combobox. | "large" | "standard" |
'standard' |
value |
value |
Value of the combobox. (controlled field) | string | string[] |
undefined |
valueViewerFormatter |
– | Function to customize how to display all selected options of the combobox. | (selectedOptions: string[]) => string | HTMLElement |
null |
variant |
variant |
Variant of the combobox. | "filled" | "outline" |
'outline' |
| Event | Description | Type |
|---|---|---|
valueChanged |
Event fired every time the value of the combobox is changed, it receives an object with the newValue and the oldValue. | CustomEvent<{ newValue: string | string[]; oldValue: string | string[]; }> |
closeCombobox(haveToFocus?: boolean) => Promise<void>| Name | Type | Description |
|---|---|---|
haveToFocus |
boolean |
Type: Promise<void>
openCombobox() => Promise<void>Type: Promise<void>
setDefaultValue(newDefaultValue: string | string[]) => Promise<void>Method to set the default value of the combobox.
| Name | Type | Description |
|---|---|---|
newDefaultValue |
string | string[] |
Type: Promise<void>
setOptions(options: ComboboxOptionOrDividerType[]) => Promise<void>Method to set the options of the combobox.
| Name | Type | Description |
|---|---|---|
options |
ComboboxOptionOrDividerType[] |
Type: Promise<void>
setSelectedValueFormatter(newSelectedValueFormatter: SelectedValueFormatterType) => Promise<void>Method to set the selected value formatter function of the combobox.
| Name | Type | Description |
|---|---|---|
newSelectedValueFormatter |
(selectedOption: ComboboxOptionOrDividerType, selectedOptions: string[]) => HTMLElement |
Type: Promise<void>
setValue(newValue: string | string[]) => Promise<void>Method to set the value of the combobox.
| Name | Type | Description |
|---|---|---|
newValue |
string | string[] |
Type: Promise<void>
| Slot | Description |
|---|---|
"placeholder" |
Slot to render the placeholder. |
"prefix" |
Slot to render a prefix inside the trigger element. |
"suffix" |
Slot to render a suffix inside the trigger element. |