Dropdown | Calcite Design System

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

Overview

Dropdowns can be single or multi-selectable lists. Every Dropdown Item must have a parent Dropdown Group. For more information, refer to Grouping Dropdown Items.

Sample

Component comparison

Dropdown

This component

Often used to select from known sets of items.

Provides flexibility to choose an invoking element such as a Button or Action.

Supports single and multiple selection, as well as action lists with no selection, through Dropdown Group's selectionMode property.

Combobox

Alternative

Often used to select from known sets of items.

Includes built-in filtering, state, selection, and custom item creation.

Supports various selectionMode options, including single and multiple selection.

Select

Alternative

Often used for selecting a single option from a small list of options.

Provides the native browser select menu with Option text labels only.

Supports single selection.

Usage

Filter and sort interactions
Selection lists

Best practices

Every Dropdown Item must have a parent Dropdown Group.

Use multiple Dropdown Groups within a single Dropdown to allow a user to make independent selections from each. For example, a Dropdown could include separate Dropdown Groups for sorting by date, name, and rating. Selections in one Dropdown Group do not affect selections in other Dropdown Groups, and each Dropdown Group can define its own selectionMode.

When a Dropdown Group's selectionMode is set to "none", the group can categorize related items within a Dropdown. Grouping related items under meaningful titles creates a collection of items, which is useful for users to find items more readily.

A Dropdown with a selected Dropdown Item in each of the Dropdown Groups: creation date, priority, and distance .

Do use multiple Dropdown Groups to provide independent selections within one Dropdown.

A Dropdown with related Dropdown Items grouped in the export and share Dropdown Groups.

Do use multiple Dropdown Groups with selectionMode set to "none" to categorize items within a Dropdown.

Use Button or Action as reference elements

Dropdowns should be invoked by an interactive reference element such as Button or Action. The components are designed to initiate interactions, making them good choices for activating a Dropdown. Use the referenceElement property to associate a Dropdown with its reference element and position it relative to that element.

A Dropdown initiated from a Button to change views.

Do use interactive elements such as a Button to invoke Dropdowns.

A Dropdown initiated from an Action to insert a shape.

Do use interactive elements such as an Action to invoke Dropdowns.

Keep multi-select Dropdowns open after selection

When a Dropdown Group has selectionMode set to "multiple", consider setting closeOnSelectDisabled to true to allow multiple selections without needing to reopen the Dropdown.

Consider setting closeOnSelectDisabled to true when selectionMode is set to "multiple".

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>`