Combobox
Calcite Combobox is an input and dropdown-based selection system which allows for quick filtering of single and multi-selections.
Overview
Combobox is designed to be used in situations where a dropdown or list has a large amount of choices to sift through. The type-ahead property of Combobox allows the user to quickly type and search for selections.
Multi-select Combobox utilizes Chips to display selected items that can quickly be deleted by clicking the X icon or hitting backspace when focused.
Usage
- Multi-select purposes
- Filtering
Sample
Accessibility
Keyboard navigation
| Key | Function |
|---|---|
Arrow up | Move focus to previous item. If the current focus is the first item, the focus will cycle last item |
Arrow down | Move focus to next item. If the current focus is the last item, the focus will cycle to the first item |
Tab | Move focus to next item. If the current focus is the last item, the focus will return to input |
Tab and Shift | Move focus to previous item. If the current focus is the first item, the focus will return to input |
API reference
Properties
| Property | Attribute | Description | Type | Values |
|---|---|---|---|---|
| active | active | Opens or closes the combobox | truefalse | |
| allowCustomValues | allow-custom-values | Allow entry of custom values which are not in the original set of items | truefalse | |
| disabled | disabled | Disable combobox input | truefalse | |
| flipPlacements | Defines the available placements that can be used when a flip occurs. | ComputedPlacement[] | ||
| intlRemoveTag | intl-remove-tag | string to override the English "Remove tag" text for when an item is selected. | "Remove tag" (default) | |
| label | label | Aria label for combobox (required) | undefined | |
| maxItems | max-items | Specify the maximum number of combobox items (including nested children) to display before showing the scroller | 0 (default) | |
| name | name | The name of the switch input | undefined | |
| overlayPositioning | overlay-positioning | Describes the type of positioning to use for the overlaid content. If your element is in a fixed container, use the 'fixed' value. | absolute (default)fixed | |
| placeholder | placeholder | Placeholder text for input | undefined | |
| scale | scale | Specify the scale of the combobox, defaults to m | lm (default)s | |
| selectionMode | selection-mode | specify the selection mode - multi: allow any number of selected items (default) - single: only one selection) - ancestors: like multi, but show ancestors of selected items as selected, only deepest children shown in chips | ancestorsmulti (default)single | |
| value | value | The value(s) of the selectedItem(s) |
Events
| Name | Description | Detail |
|---|---|---|
| calciteComboboxChange | Called when the selected item(s) changes. | { selectedItems: HTMLCalciteComboboxItemElement[]; } |
| calciteComboboxChipDismiss | Called when a selected item in the combobox is dismissed via its chip | any |
| calciteComboboxFilterChange | Called when the user has entered text to filter the options list | { visibleItems: HTMLCalciteComboboxItemElement[]; text: string; } |
| calciteLookupChange | Called when the selected items set changes | HTMLCalciteComboboxItemElement[] |
Methods
| Name | Description | Signature | Returns |
|---|---|---|---|
| reposition | Updates the position of the component. | reposition() => Promise<void> | Promise<void> |
| setFocus | Sets focus on the component. | setFocus() => Promise<void> | Promise<void> |
Slots
| Name | Description |
|---|---|
| default (unnamed) | A slot for adding `calcite-combobox-item`s. |
Styles
| Name | Description | CSS Variable |
|---|---|---|
| --calcite-combobox-input-height | the height of the combobox input | --calcite-combobox-input-height |