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 | true false | |
allowCustomValues | allow-custom-values | Allow entry of custom values which are not in the original set of items | true false | |
disabled | disabled | Disable combobox input | true false | |
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 | l m (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 | ancestors multi (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 |