Usage
Dropdown shows a menu of actions or options, revealed from a toggle. Put the trigger in the toggle slot and the menu contents — Dropdown Item elements, optionally organised with a Dropdown Group or nested in a Dropdown Submenu — in the default slot.
Import the parts you need — each import registers its custom element:
import "@nordhealth/components/lib/Dropdown"
import "@nordhealth/components/lib/DropdownItem"
import "@nordhealth/components/lib/DropdownGroup"
import "@nordhealth/components/lib/DropdownSubmenu"
Then compose a toggle with its menu:
Composition
A dropdown pairs a toggle with a menu of items, which can be grouped or nested.
Dropdown
├── Button (slot="toggle")
├── DropdownItem
├── DropdownGroup
│ └── DropdownItem
└── DropdownSubmenu
├── DropdownItem (slot="trigger")
└── DropdownItem
<nord-dropdown>
<nord-button slot="toggle">Menu</nord-button>
<nord-dropdown-item>Option</nord-dropdown-item>
</nord-dropdown>
Dropdown
Dropdown is the container. The element in the toggle slot opens and closes the menu; size, align, position and always-floating control how the menu is presented.
Dropdown Item
Dropdown Item is a single action or option. Give it an href to render as a link, or add slot="start" / slot="end" content for icons and adornments.
Dropdown Group
Dropdown Group clusters related items under an optional heading.
Dropdown Submenu
Dropdown Submenu nests a secondary menu. Put the item that opens it in the trigger slot, and the nested items in the default slot.
Examples
Basic
A simple menu of actions.
Grouped items
Use a Dropdown Group with a heading to label a section of the menu.
Submenu
Nest a secondary menu with a Dropdown Submenu.
With a header
Place fixed content above the scrollable items using the header slot — useful for showing the current account or context the menu acts on.
With messages
Combine dropdown items with Banner messages to surface status or contextual information inside the menu.
Badge as toggle
Any element can act as the trigger via the toggle slot. Here a Badge opens the menu.
Clinic switcher
A real-world pattern: an expanding dropdown in the navigation header that lets the user switch between clinics.
Complex menu
A richer menu combining groups, icons, descriptions and a submenu.
Always floating
By default the dropdown becomes a full-width sheet on small viewports. Add always-floating to keep it as a floating overlay at every viewport size.
Position and alignment
The position attribute places the menu relative to its trigger (block-end, block-start, inline-start, inline-end, or auto), and align (start or end) shifts it along that edge.
Inline size
Constrain the width of the menu with the size and inline-size styling so long items wrap or truncate predictably.
Maximum block size
Cap the height of the menu so long lists scroll inside the dropdown instead of overflowing the viewport.
RTL
Dropdown follows the document or container direction. Toggle the direction to see the layout mirror.
Accessibility
- The toggle and menu implement the menu-button keyboard pattern: open with Enter / Space, move between items with the arrow keys, and close with Esc.
- Keep Dropdown Item labels short and action-oriented. Don't place unrelated interactive controls inside the menu.
- Use a Dropdown for menus and commands — for selecting a form value, use Select or Combobox instead.
API reference
Dropdown
Dropdown menu displays a list of actions or selectable options for a user. Dropdown uses popout component internally to create the overlay functionality.
<nord-dropdown></nord-dropdown>Props
| 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' |
sideOffset | side-offset | Distance in pixels from the toggle (or anchor) along the main axis — the
gap between the floating element and the side it opens against. Fed into
Floating UI's offset middleware as mainAxis. Defaults to 8. | number | 8 |
alignOffset | align-offset | Offset in pixels along the alignment axis — slides the floating element
toward the start or end of the toggle (or anchor). Fed into Floating
UI's offset middleware as alignmentAxis. Defaults to 0. | number | 0 |
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 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 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 |
Parts
This component is made up of the following parts.
Dropdown Group
Dropdown group includes all the actions or items in a single dropdown group and is used for grouping items into related categories.
<nord-dropdown-group></nord-dropdown-group>Props
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
heading | heading | Heading and accessible label for the dropdown group. | string | undefined | — |
Slots
| Slot name | Description |
|---|---|
Default slot | The dropdown group content. |
Dropdown Item
Dropdown item populates dropdown with actions. Items can be placed either inside a dropdown group or directly inside a dropdown component.
<nord-dropdown-item></nord-dropdown-item>Props
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
href | href | The url the dropdown item should link to. | string | undefined | — |
target | target | When provided together with a href property, determines where to open the linked URL. The keywords have special meanings for where to load the URL: “_self” means the current browsing context, “_blank” usually a new tab but users can configure browsers this to open a new window instead, “_parent” means the parent browsing context of the current one, but if no parent exists, behaves as _self, and finally “top” means the topmost browsing context. | '_self' | '_blank' | '_parent' | '_top' | '_self' |
disabled | disabled | Makes the component disabled. This prevents users from being able to interact with the component, and conveys its inactive state to assistive technologies. | boolean | false |
Slots
| Slot name | Description |
|---|---|
Default slot | The dropdown item content. |
start | Used to place content before dropdown item text. Typically used for icons. |
end | Used to place content after dropdown item text. Typically used for icons. |
Methods
| Method name | Parameters | Description |
|---|---|---|
focus(options?: FocusOptions) => void | options: An object which controls aspects of the focusing process. | Programmatically move focus to the component. |
blur() => void | N/A | Programmatically remove focus from the component. |
click() => void | N/A | Programmatically simulates a click on the component. |
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-item-background-color | Controls the background color of the item, using our color tokens. | transparent |
--n-dropdown-item-color | Controls the color of the text within the item, using our color tokens. | var(--n-color-text) |
--n-dropdown-item-white-space | Controls how the item's label handles whitespace. Set to normal to allow long labels to wrap across multiple lines instead of truncating with an ellipsis. | nowrap |
--n-dropdown-item-align-items | Controls how the item's contents (start slot, label, end slot) align on the cross axis. Useful with multi-line wrapping: set to flex-start so icons/avatars sit on the first line instead of the vertical middle. | center |
Dropdown Submenu
Dropdown submenu nests a secondary menu within a parent dropdown.
<nord-dropdown-submenu></nord-dropdown-submenu>Slots
| Slot name | Description |
|---|---|
trigger | The element that opens the submenu (typically nord-dropdown-item). |
Default slot | The submenu content items. |
Methods
| Method name | Parameters | Description |
|---|---|---|
close() => Promise<TransitionEvent | void> | N/A | Close the submenu programmatically. Returns a promise that resolves when the close animation completes. |
Dependencies
This component is internally dependent on the following components:
- <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.
Design guidelinesFor designers
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.