Combobox

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

5 samples
1
2
3
4
5
6
7
8
9
10
<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>
v3.0.0

Best practices

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

Accessibility

Keyboard navigation

KeyFunction
BackspaceWhen the component is focused and contains a selected calcite-combobox-item will remove the most recently added from the component.
SpaceIf the component is not open, opens the component.
Arrow upOnce 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 downOnce 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.
EnterIf the component is open and a calcite-combobox-item is active, will toggle it's selected state.
EscIf the component is open, closes the component.
TabMoves focus in and out of the component.
Tab and ShiftMoves focus in and out of the component.

API reference

Properties

PropertyAttributeDescriptionTypeDefault
allowCustomValuesallow-custom-valuesWhen true, allows entry of custom values, which are not in the original set of items.booleanfalse
clearDisabledclear-disabledWhen true, the value-clearing will be disabled.booleanfalse
disableddisabledWhen true, interaction is prevented and the component is displayed with lower opacity.booleanfalse
filteredItemsread-onlySpecifies the component's filtered items.Array<HTMLCalciteComboboxItemElement>
filterPropsSpecifies the properties to match against when filtering. If not set, all properties will be matched (label, description, metadata, value).Array<string>
filterTextfilter-textText for the component's filter input field.string
flipPlacementsSpecifies 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">
formformThe 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
labelrequiredlabelAccessible name for the component.string
maxItemsmax-itemsSpecifies the maximum number of calcite-combobox-items (including nested children) to display before displaying a scrollbar.number0
messageOverridesUse this property to override individual strings used by the component.{ all?: string; allSelected?: string; clear?: string; removeTag?: string; selected?: string; }
namenameSpecifies the name of the component. Required to pass the component's value on form submission.string
openopenWhen true, displays and positions the component.booleanfalse
overlayPositioningoverlay-positioningDetermines 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"
placeholderplaceholderSpecifies the placeholder text for the input.string
placeholderIconplaceholder-iconSpecifies the placeholder icon for the input.string
placeholderIconFlipRtlplaceholder-icon-flip-rtlWhen true, the icon will be flipped when the element direction is right-to-left ("rtl").booleanfalse
readOnlyread-onlyWhen true, the component's value can be read, but controls are not accessible and the value cannot be modified.booleanfalse
requiredrequiredWhen true and the component resides in a form, the component must have a value in order for the form to submit.booleanfalse
scalescaleSpecifies the size of the component."l" | "m" | "s""m"
selectedItemsread-onlySpecifies the component's selected items.Array<HTMLCalciteComboboxItemElement>
selectionDisplayselection-displayWhen selectionMode is "ancestors" or "multiple", specifies the display of multiple calcite-combobox-item selections, where: "all" displays all selections with individual calcite-chips, "fit" displays individual calcite-chips 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"
selectionModeselection-modeSpecifies 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"
statusstatusSpecifies the status of the input field, which determines message and icons."idle" | "invalid" | "valid""idle"
validationIconvalidation-iconSpecifies the validation icon to display under the component.boolean | string
validationMessagevalidation-messageSpecifies the validation message to display under the component.string
validityread-onlyThe 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; }
valuevalueThe component's value(s) from the selected calcite-combobox-item(s).Array<string> | string

Slots

NameDescription
default (unnamed)A slot for adding calcite-combobox-items.

Styles

NameDescription
--calcite-combobox-input-heightSpecifies the height of the component's input.

Events

NameDescriptionBehavior
calciteComboboxBeforeCloseFires when the component is requested to be closed, and before the closing transition begins.bubblescomposed
calciteComboboxBeforeOpenFires when the component is added to the DOM but not rendered, and before the opening transition begins.bubblescomposed
calciteComboboxChangeFires when the selected item(s) changes.bubblescomposed
calciteComboboxChipCloseFires when a selected item in the component is closed via its calcite-chip.bubblescomposed
calciteComboboxCloseFires when the component is closed and animation is complete.bubblescomposed
calciteComboboxFilterChangeFires when text is added to filter the options list.bubblescomposed
calciteComboboxOpenFires when the component is open and animation is complete.bubblescomposed

Methods

NameDescriptionSignature
componentOnReadyCreate a promise that resolves once component is fully loaded.componentOnReady(): Promise<void>
repositionUpdates the position of the component.reposition(delayed?: boolean): Promise<void>
setFocusSets focus on the component.setFocus(): Promise<void>

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

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close