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.
Usage
- Filter and sort interactions
- Selection lists
Sample
Accessibility
Keyboard navigation
| 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 close is false (default), closes the component. |
Space | Selects the active calcite-dropdown-item and when close 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-items when their initial or specified placement has insufficient space available. | FlipPlacement[] | ||
| maxItems | max-items | Specifies the maximum number of calcite-dropdown-items to display before showing a scrollbar.
Value must be greater than 0, and does not include groupTitles 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. | MenuPlacement | "bottom-start" |
| scale | scale | Specifies the size of the component. | Scale | "m" |
| selectedItems | 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 | width property instead. | 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 | 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. | |
| calciteDropdownBeforeOpen | Fires when the component is added to the DOM but not rendered, and before the opening transition begins. | |
| calciteDropdownClose | Fires when the component is closed and animation is complete. | |
| calciteDropdownOpen | Fires when the component is opened and animation is complete. | |
| calciteDropdownSelect | Fires when a calcite-dropdown-item's selection changes. |
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's first focusable element. | setFocus(options?: FocusOptions): Promise<void> |