Dropdown
Dropdown menu displays a list of actions or selectable options for a user. Dropdown uses popout component internally to create the overlay functionality.
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
expand | expand | Controls whether the toggle slot expands to fill the width of its container. | boolean | false |
size | size | The size of the dropdown. This affects the minimum and maximum inline-size of the dropdown. | 's' | 'm' | 'l' | 'm' |
alwaysFloating | always-floating | Set to true to always display the dropdown as a floating overlay, even on smaller viewports. | boolean | false |
open | open | Controls whether the component is open or not. | boolean | false |
align | align | Set the alignment in relation to the toggle (or anchor) depending on the position. `start` will align it to the left of the toggle (or anchor). `end` will align it to the right of the toggle (or anchor). Setting the `position` to `inline-start` or `inline-end` will switch `start` and `end` to the top and bottom respectively. | 'start' | 'end' | 'start' |
position | position | Set the position in relation to the toggle (or anchor). Options follow logical properties. `block-start` and `block-end` referring to top and bottom respectively, `inline-start` and `inline-end` referring to left and right respectively. You can also set it to `auto` for automatic positioning depending on which side has the most space available. | 'block-end' | 'block-start' | 'inline-start' | 'inline-end' | 'auto' | 'block-end' |
Slots
| Slot name | Description |
|---|---|
Default slot | The dropdown content. |
toggle | Used to place the toggle for dropdown. |
header | Optional slot that holds a header for the dropdown. |
header-end | Optional slot that positions content at the end of the header. Useful for actions or additional info. |
Methods
| Method name | Parameters | Description |
|---|---|---|
hide(moveFocusToButton?: boolean) => Promise<TransitionEvent | void> | moveFocusToButton: A boolean option to move the focus to the original button that opens the dropdown. | Hide the dropdown programmatically. This method delegates to the Dropdown's internal Popout component. See [Popout's hide() method](/components/popout#methods-hide) for more details. |
show() => Promise<TransitionEvent | void> | N/A | Show the dropdown programmatically. This method delegates to the Dropdown's internal Popout component. See [Popout's show() method](/components/popout#methods-hide) for more details. |
| Event | Detail Type | Description |
|---|---|---|
open | NordEvent | Dispatched when the popout is opened. |
close | NordEvent | Dispatched when the popout is closed. |
CSS Properties
CSS Custom Properties provide more fine grain control over component presentation. We advise utilizing existing properties on the component before using these.
| Property | Description | Default |
|---|---|---|
--n-dropdown-size | Controls the inline size, or width, of the dropdown. Will resize up to 1.5 times to account for larger content. | 250px |
--n-dropdown-max-block-size | Controls the maximum block size, or height, of the dropdown. Larger content will get a scrollbar. | 460px |
Dependencies
This component is internally dependent on the following components:
- <nord-dropdown-item>
DropdownItem
Dropdown item populates dropdown with actions. Items can be placed either inside a dropdown group or directly inside a dropdown component.
- <nord-icon>
Icon
Icons are used to provide additional meaning or in places where text label doesn’t fit. Icon component allows you to display an icon from the Nordicons library.
- <nord-popout>
Popout
Popouts are small overlays that open on demand. They let users access additional content and actions without cluttering the page.
Usage
This section includes guidelines for designers and developers about the usage of this component in different contexts.
Do
- Dropdown menus are typically used when you have 5-15 items to choose from. They’re used for navigation or commands, where an action is initiated based on the selection.
- When organizing dropdown menu items, sort the list in a logical order by putting the most selected option at the top.
- Use for a “more” menu, where the control contains an icon.
- Use for user profiles, where the control is an avatar.
- Use in conjunction with the dropdown item and dropdown group components.
Don’t
- Don't use for form inputs or selects, use the select component or input component instead.
- Don't use for hiding primary actions since they should be visible by default.
- Don't nest elements or components other than the dropdown item and dropdown group components. Consider using the popout component when creating custom UI.
- Don't use
always-floatingproperty for long lists or complex content that benefits from full-screen focus.
Content guidelines
Dropdown items should be always written in sentence case, not title case. The first word should be capitalized and the rest lowercase (unless a proper noun):
Dropdown items should always lead with a strong verb that encourages action. Use the {verb}+{noun} format except in the case of common actions like Save, Close or Cancel:
Avoid unnecessary words and articles in dropdown items, such as “the”, “an” or “a”:
Avoid ending dropdown items in punctuation:
Avoid all caps for dropdown items:
Keep dropdown items to a single line of text:
of the veterinary application.
Additional considerations
- Consider using the
alwaysFloatingproperty for compact dropdown menus that work well in a small floating container.
Integration
For integration guidelines, please see Web Components documentation .