Dropdown | Calcite Design System | Esri Developer

Dropdowns are floating lists that can be revealed by an event such as a button click or select tag.

Overview

Dropdowns can be single or multi-selectable lists. Every Dropdown Item must have a parent Dropdown Group.

Sample

Usage

Filter and sort interactions
Selection lists

Accessibility

Key	Function
`Arrow down`	If the component is not `open`, opens the component. When `open`, moves focus to next non-disabled `calcite-dropdown-item`. If the current focus is the last `calcite-dropdown-item`, focus will cycle to the first `calcite-dropdown-item`.
`Arrow up`	If the component is not `open`, opens the component. When `open`, moves focus to previous non-disabled `calcite-dropdown-item`. If the current focus is the first `calcite-dropdown-item`, the focus will cycle to the last `calcite-dropdown-item`.
`Esc`	If the component is `open`, closes the component.
`Home`	Moves focus to the component's first `calcite-dropdown-item`.
`End`	Moves focus to the component's last `calcite-dropdown-item`.
`Enter`	Selects the active `calcite-dropdown-item` and when `closeOnSelectDisabled` is `false` (default), closes the component.
`Space`	Selects the active `calcite-dropdown-item` and when `closeOnSelectDisabled` is `false` (default), 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
closeOnSelectDisabled	close-on-select-disabled	When `true`, the component will remain open after a selection is made. If the `selectionMode` of the selected `calcite-dropdown-item`'s containing `calcite-dropdown-group` is `"none"`, the component will always close.	`boolean`	`false`
disabled	disabled	When `true`, prevents interaction and decreases the component's opacity.	`boolean`	`false`
flipPlacements		Specifies the component's fallback `placement` for slotted `calcite-dropdown-item`s when their initial or specified `placement` has insufficient space available.	`FlipPlacement[]`
maxItems	max-items	Specifies the maximum number of `calcite-dropdown-item`s to display before showing a scrollbar. Value must be greater than `0`, and does not include `groupTitle`s from `calcite-dropdown-group`.	`number`	`0`
offsetDistance	offset-distance	Specifies the distance to position the component away from the `referenceElement`.	`number`	`0`
offsetSkidding	offset-skidding	Specifies the distance to position the component along the `referenceElement`.	`number`	`0`
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"`
placement	placement	Determines the component's placement relative to the container element.	`LogicalPlacement`	`"bottom-start"`
referenceElement	reference-element	The `referenceElement` is used to position the component according to its `placement` value. Setting the value to an `HTMLElement` is preferred so the component does not need to query the DOM. However, a string `id` of the reference element can also be used. The component should not be placed within its own `referenceElement` to avoid unintended behavior.	`ReferenceElement \| string \| null`
scale	scale	Specifies the size of the component.	`Scale`	`"m"`
selectedItemsread-only		The component's selected items.	`DropdownItem[]`
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`
type	type	Specifies the type of action on the container element to open the component.	`"hover" \| "click"`	`"click"`
width	width	Specifies the component's width.	`Extract<Width, Scale>`
widthScale	width-scale	deprecatedin v3.0.0, removal target v6.0.0 - Use the `width` property instead. Specifies the component's width.	`Scale`

Slots

Name	Description
default (unnamed)	A slot for adding `calcite-dropdown-group` elements. Every `calcite-dropdown-item` must have a parent `calcite-dropdown-group`, even if the `groupTitle` property is not set.
trigger	deprecated in v5.1.0, removal target v7.0.0 - Use the `referenceElement` property instead. A slot for the element that triggers the component.

Styles

Name	Description
--calcite-dropdown-width	Specifies the width of the component's wrapper.
--calcite-dropdown-background-color	Specifies the component's background color.

Events

Name	Description	Behavior
calciteDropdownBeforeClose	Fires when the component is requested to be closed and before the closing transition begins.	bubblescomposed
calciteDropdownBeforeOpen	Fires when the component is added to the DOM but not rendered, and before the opening transition begins.	bubblescomposed
calciteDropdownClose	Fires when the component is closed and animation is complete.	bubblescomposed
calciteDropdownOpen	Fires when the component is opened and animation is complete.	bubblescomposed
calciteDropdownSelect	Fires when a `calcite-dropdown-item`'s selection changes.	bubblescomposed

Methods

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