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

Show code snippetCopy code snippet
Edit sample on Codepen
v1.0.0-beta.83
Toggle preview themeToggle preview direction

Accessibility

Keyboard navigation

KeyFunction
Arrow upMove focus to previous item. If the current focus is the first item, the focus will cycle last item
Arrow downMove focus to next item. If the current focus is the last item, the focus will cycle to the first item
TabMove focus to next item. If the current focus is the last item, the focus will return to input
Tab and ShiftMove focus to previous item. If the current focus is the first item, the focus will return to input

API reference

calcite-combobox
v1.0.0-beta.83

Properties

PropertyAttributeDescriptionTypeValues
activeactive

Opens or closes the combobox

booleanA boolean property should be present, or not
truefalse
allowCustomValuesallow-custom-values

Allow entry of custom values which are not in the original set of items

booleanA boolean property should be present, or not
truefalse
disableddisabled

Disable combobox input

booleanA boolean property should be present, or not
truefalse
flipPlacements

Defines the available placements that can be used when a flip occurs.

optional
typedChoose from a set of typed values
ComputedPlacement[]
intlRemoveTagintl-remove-tag

string to override the English "Remove tag" text for when an item is selected.

stringA custom string
"Remove tag" (default)
labellabel

Aria label for combobox (required)

required
stringA custom string
undefined
maxItemsmax-items

Specify the maximum number of combobox items (including nested children) to display before showing the scroller

numberA number
0 (default)
namename

The name of the switch input

stringA custom string
undefined
overlayPositioningoverlay-positioning

Describes the type of positioning to use for the overlaid content. If your element is in a fixed container, use the 'fixed' value.

typedChoose from a set of typed values
absolute (default)fixed
placeholderplaceholder

Placeholder text for input

optional
stringA custom string
undefined
scalescale

Specify the scale of the combobox, defaults to m

typedChoose from a set of typed values
lm (default)s
selectionModeselection-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

typedChoose from a set of typed values
ancestorsmulti (default)single
valuevalue

The value(s) of the selectedItem(s)

typedChoose from a set of typed values

Events

NameDescriptionDetail
calciteComboboxChange

Called when the selected item(s) changes.

bubblescomposedcancelable
{ selectedItems: HTMLCalciteComboboxItemElement[]; }
calciteComboboxChipDismiss

Called when a selected item in the combobox is dismissed via its chip

bubblescomposedcancelable
any
calciteComboboxFilterChange

Called when the user has entered text to filter the options list

bubblescomposedcancelable
{ visibleItems: HTMLCalciteComboboxItemElement[]; text: string; }
calciteLookupChange
deprecateduse calciteComboboxChange instead

Called when the selected items set changes

bubblescomposedcancelable
HTMLCalciteComboboxItemElement[]

Methods

NameDescriptionSignatureReturns
reposition

Updates the position of the component.

reposition() => Promise<void>Promise<void>
setFocus

Sets focus on the component.

setFocus() => Promise<void>Promise<void>

Slots

NameDescription
default (unnamed)

A slot for adding `calcite-combobox-item`s.

Styles

NameDescriptionCSS Variable
--calcite-combobox-input-height

the height of the combobox input

--calcite-combobox-input-height

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.