Combobox | Calcite Design System

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

Best practices

Comparison

Combobox

This component

Most often used when the workflow requires multiple selections.

Best when the number of selectable items is finite and small.

Often used for accepting custom values and both single and multiple selection.

Autocomplete

Alternative

Most often used with very long or unpredictable lengths of items.

Best for programmatically returning responses based on user input.

Does not accept custom values or multiple selections.

Recommendations

To disable the ability to clear a selection when selectionMode is set to "single-persist", set the clearDisabled property to true.

Accessibility

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`, disables value-clearing.	`boolean`	`false`
disabled	disabled	When `true`, prevents interaction and decreases the component's opacity.	`boolean`	`false`
filteredItemsread-only		The component's filtered items.	`HTMLCalciteComboboxItemElement[]`
filterProps		Specifies the properties to match against when filtering. If not set, all properties will be matched (`description`, `label`, `metadata`, `shortHeading`).	`string[]`
filterText	filter-text	The component's filter input field text.	`string`
flipPlacements		Specifies the component's fallback `placement` for slotted content when it's initial or specified `placement` has insufficient space available.	`FlipPlacement[]`
form	form	Specifies the `id` of the component's associated form. When not set, the component is associated with its ancestor form element, if one exists.	`string`
labelrequired	label	Specifies an accessible label for the component.	`string`
labelText	label-text	Specifies the component's label text.	`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		Overrides individual strings used by the component.	`Record<string, unknown> \| undefined`
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	Specifies the type of positioning to use for overlaid content, where: `"absolute"` works for most cases - positioning the component inside of overflowing parent containers, which affects the container's layout, and `"fixed"` is used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.	`OverlayPositioning`	`"absolute"`
placeholder	placeholder	Specifies the input's placeholder text.	`string`
placeholderIcon	placeholder-icon	Specifies the input's placeholder icon.	`IconName`
placeholderIconFlipRtl	placeholder-icon-flip-rtl	When `true` and the element direction is right-to-left (`"rtl"`), flips the input's `placeholderIcon`.	`boolean`	`false`
placement	placement	Specifies the component's position relative to the `referenceElement`.	`LogicalPlacement`	`"bottom-start"`
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.	`Scale`	`"m"`
selectAllEnabled	select-all-enabled	When `true` and `selectionMode` is `"multiple"` or `"ancestors"`, displays a checkbox for selecting all `calcite-combobox-item`s.	`boolean`	`false`
selectedItemsread-only		The component's selected items.	`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.	`SelectionDisplay`	`"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.	`Extract<"single" \| "single-persist" \| "ancestors" \| "multiple", SelectionMode>`	`"multiple"`
status	status	Specifies the input field's status, which determines message and icons.	`Status`	`"idle"`
topLayerDisabled	top-layer-disabled	When `true` and the component is `open`, disables top layer placement. Only set this if you need complex z-index control or if top layer placement causes conflicts with third-party components.	`boolean`	`false`
validationIcon	validation-icon	Specifies the validation icon to display under the component.	`IconName \| boolean`
validationMessage	validation-message	Specifies the validation message to display under the component.	`string`
validityread-only		The component's current validation state.	`MutableValidityState`
value	value	The component's value(s) from the selected `calcite-combobox-item`(s).	`string \| string[]`

Slots

Name	Description
default (unnamed)	A slot for adding `calcite-combobox-item`s.
label-content	A slot for rendering content next to the component's `labelText`.

Styles

Name	Description
--calcite-combobox-divider-color	Specifies the component's divider color.
--calcite-combobox-icon-color	Specifies the component's icon color.
--calcite-combobox-icon-color-hover	Specifies the component's icon color when hovered.
--calcite-combobox-background-color	Specifies the background color of the component's listbox.
--calcite-combobox-input-border-color	Specifies the border color of the component's input.
--calcite-combobox-input-background-color	Specifies the background color of the component's input.
--calcite-combobox-input-height	Specifies the height of the component's input.
--calcite-combobox-input-text-color	When `selectionDisplay` is `"single"`, specifies the text color 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.	bubblescomposed
calciteComboboxBeforeOpen	Fires when the component is added to the DOM but not rendered, and before the opening transition begins.	bubblescomposed
calciteComboboxChange	Fires when the selected item(s) changes.	bubblescomposed
calciteComboboxChipClose	Fires when a selected item in the component is closed via its `calcite-chip`.	bubblescomposed
calciteComboboxClose	Fires when the component is closed and animation is complete.	bubblescomposed
calciteComboboxFilterChange	Fires when text is added to filter the options list.	bubblescomposed
calciteComboboxOpen	Fires when the component is open and animation is complete.	bubblescomposed

Methods

Name	Description	Signature
componentOnReady	Create a promise that resolves once component is fully loaded.	`componentOnReady(): Promise<this>`
reposition	Updates the component's position.	`reposition(delayed?: boolean): Promise<void>`
setFocus	Sets focus on the component.	`setFocus(options?: FocusOptions): Promise<void>`