Combobox is an input and dropdown-based selection, which allows for quick filtering of single and multi-selections.
Overview
Combobox is designed for 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 available selections.
Multi-select Combobox utilizes Chips to display selected items, which can quickly be deleted by selecting the "Closable" icon or pressing the Backspace
key when focused.
Usage
- Multi-select purposes
- Filtering
Sample
<calcite-combobox placeholder="Select a field">
<calcite-combobox-item value="Natural Resources" heading="Natural Resources"></calcite-combobox-item>
<calcite-combobox-item value="agriculture" heading="Agriculture"></calcite-combobox-item>
<calcite-combobox-item value="forestry" heading="Forestry"></calcite-combobox-item>
<calcite-combobox-item value="mining" heading="Mining"></calcite-combobox-item>
<calcite-combobox-item value="business" heading="Business"></calcite-combobox-item>
<calcite-combobox-item value="education" heading="Education"></calcite-combobox-item>
<calcite-combobox-item value="utilities" heading="Utilities"></calcite-combobox-item>
<calcite-combobox-item value="transportation" heading="Transportation"></calcite-combobox-item>
</calcite-combobox>
Best practices
To disable the ability to clear a selection when selection
is set to "single-persist"
, set the clear
property to true
.
Accessibility
Keyboard navigation
Key | Function |
---|---|
Backspace | When the component is focused and contains a selected calcite-combobox-item will remove the most recently added from the component. |
Space | If the component is not open , opens the component. |
Arrow up | Once the component is open and in focus, moves focus to previous calcite-combobox-item . If the current focus is the first calcite-combobox-item , focus will cycle to the last calcite-combobox-item . |
Arrow down | Once the component is open and in focus, move focus to next calcite-combobox-item . If the current focus is the last calcite-combobox-item , focus will cycle to the first calcite-combobox-item . |
Enter | If the component is open and a calcite-combobox-item is active , will toggle it's selected state. |
Esc | If the component is open , closes the component. |
Tab | Moves focus in and out of the component. |
Tab and Shift | Moves focus in and out of the component. |
API reference
Properties
Property | Attribute | Description | Type | Default |
---|---|---|---|---|
allowCustomValues | allow-custom-values | When true , allows entry of custom values, which are not in the original set of items. | boolean | false |
clearDisabled | clear-disabled | When true , the value-clearing will be disabled. | boolean | false |
disabled | disabled | When true , interaction is prevented and the component is displayed with lower opacity. | boolean | false |
filteredItems | Specifies the component's filtered items. | Array<HTMLCalciteComboboxItemElement> | ||
filterProps | Specifies the properties to match against when filtering. If not set, all properties will be matched (label, description, metadata, value). | Array<string> | ||
filterText | filter-text | Text for the component's filter input field. | string | |
flipPlacements | Specifies the component's fallback slotted content placement when it's initial placement has insufficient space available. | Array<"top" | "bottom" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "right-start" | "right-end" | "left-start" | "left-end" | "leading-start" | "leading" | "leading-end" | "trailing-end" | "trailing" | "trailing-start"> | ||
form | form | The id of the form that will be associated with the component.
When not set, the component will be associated with its ancestor form element, if any. | string | |
label | label | Accessible name for the component. | string | |
maxItems | max-items | Specifies the maximum number of calcite-combobox-item s (including nested children) to display before displaying a scrollbar. | number | 0 |
messageOverrides | Use this property to override individual strings used by the component. | {
all?: string;
allSelected?: string;
clear?: string;
removeTag?: string;
selected?: string;
} | ||
name | name | Specifies the name of the component.
Required to pass the component's value on form submission. | string | |
open | open | When true , displays and positions the component. | boolean | false |
overlayPositioning | overlay-positioning | Determines the type of positioning to use for the overlaid content.
Using "absolute" will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.
"fixed" should be used to escape an overflowing parent container, or when the reference element's position CSS property is "fixed" . | "absolute" | "fixed" | "absolute" |
placeholder | placeholder | Specifies the placeholder text for the input. | string | |
placeholderIcon | placeholder-icon | Specifies the placeholder icon for the input. | string | |
placeholderIconFlipRtl | placeholder-icon-flip-rtl | When true , the icon will be flipped when the element direction is right-to-left ("rtl" ). | boolean | false |
readOnly | read-only | When true , the component's value can be read, but controls are not accessible and the value cannot be modified. | boolean | false |
required | required | When true and the component resides in a form,
the component must have a value in order for the form to submit. | boolean | false |
scale | scale | Specifies the size of the component. | "l" | "m" | "s" | "m" |
selectedItems | Specifies the component's selected items. | Array<HTMLCalciteComboboxItemElement> | ||
selectionDisplay | selection-display | When selectionMode is "ancestors" or "multiple" , specifies the display of multiple calcite-combobox-item selections, where:
"all" displays all selections with individual calcite-chip s,
"fit" displays individual calcite-chip s that scale to the component's size, including a non-closable calcite-chip , which provides the number of additional calcite-combobox-item selections not visually displayed, and
"single" displays one calcite-chip with the total number of selections. | "all" | "fit" | "single" | "all" |
selectionMode | selection-mode | Specifies the selection mode of the component, where:
"multiple" allows any number of selections,
"single" allows only one selection,
"single-persist" allows one selection and prevents de-selection, and
"ancestors" allows multiple selections, but shows ancestors of selected items as selected, with only deepest children shown in chips. | "ancestors" | "multiple" | "single" | "single-persist" | "multiple" |
status | status | Specifies the status of the input field, which determines message and icons. | "idle" | "invalid" | "valid" | "idle" |
validationIcon | validation-icon | Specifies the validation icon to display under the component. | boolean | string | |
validationMessage | validation-message | Specifies the validation message to display under the component. | string | |
validity | The current validation state of the component. | {
valid: boolean;
badInput: boolean;
customError: boolean;
patternMismatch: boolean;
rangeOverflow: boolean;
rangeUnderflow: boolean;
stepMismatch: boolean;
tooLong: boolean;
tooShort: boolean;
typeMismatch: boolean;
valueMissing: boolean;
} | ||
value | value | The component's value(s) from the selected calcite-combobox-item (s). | Array<string> | string |
Slots
Name | Description |
---|---|
default (unnamed) | A slot for adding calcite-combobox-item s. |
Styles
Name | Description |
---|---|
--calcite-combobox-input-height | Specifies the height of the component's input. |
Events
Name | Description | Behavior |
---|---|---|
calciteComboboxBeforeClose | Fires when the component is requested to be closed, and before the closing transition begins. | |
calciteComboboxBeforeOpen | Fires when the component is added to the DOM but not rendered, and before the opening transition begins. | |
calciteComboboxChange | Fires when the selected item(s) changes. | |
calciteComboboxChipClose | Fires when a selected item in the component is closed via its calcite-chip . | |
calciteComboboxClose | Fires when the component is closed and animation is complete. | |
calciteComboboxFilterChange | Fires when text is added to filter the options list. | |
calciteComboboxOpen | Fires when the component is open and animation is complete. |
Methods
Name | Description | Signature |
---|---|---|
componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<void> |
reposition | Updates the position of the component. | reposition(delayed?: boolean): Promise<void> |
setFocus | Sets focus on the component. | setFocus(): Promise<void> |