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, interaction is prevented and the component is displayed with lower opacity. | boolean | false |
| flipPlacements | Specifies the component's fallback calcite-dropdown-item placement when it's initial or specified placement has insufficient space available. | Array<"top" | "bottom" | "left" | "right" | "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"> | ||
| maxItems | max-items | Specifies the maximum number of calcite-dropdown-items to display before showing a scroller.
Value must be greater than 0, and does not include groupTitle's from calcite-dropdown-group. | number | 0 |
| offsetDistance | offset-distance | Offset the position of the component away from the referenceElement. | number | 0 |
| offsetSkidding | offset-skidding | Offset the position of the component along the referenceElement. | number | 0 |
| open | open | When true, displays and positions the component. | boolean | false |
| overlayPositioning | overlay-positioning | Determines 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" |
| placement | placement | Determines where the component will be positioned relative to the container element. | "bottom" | "bottom-end" | "bottom-start" | "top" | "top-end" | "top-start" | "bottom-start" |
| scale | scale | Specifies the size of the component. | "l" | "m" | "s" | "m" |
| selectedItems | Specifies the component's selected items. | Array<HTMLCalciteDropdownItemElement> | ||
| type | type | Specifies the action to open the component from the container element. | "click" | "hover" | "click" |
| width | width | Specifies the width of the component. | "l" | "m" | "s" | |
| widthScale | width-scale | width property instead. | "l" | "m" | "s" |
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 calcite-dropdown. |
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 open 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<void> |
| reposition | Updates the position of the component. | reposition(delayed?: boolean): Promise<void> |
| setFocus | Sets focus on the component's first focusable element. | setFocus(options?: FocusOptions): Promise<void> |