Popout
Popouts are small overlays that open on demand. They let users access additional content and actions without cluttering the page.
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
id | id | The id for the active element to reference via aria-controls. | string | '' |
anchor | anchor | Set an optional anchor element to align against, replacing the triggering element. | string | undefined | — |
alwaysFloating | always-floating | Set to true to always display the popout 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 popout content. |
Methods
| Method name | Parameters | Description |
|---|---|---|
show() => Promise<TransitionEvent | void> | N/A | Show the popout. A promise that resolves to a `TransitionEvent` when the popout's show animation ends or is cancelled. If the popout is already open, the promise resolves immediately with `undefined`. |
hide(moveFocusToButton: boolean) => Promise<TransitionEvent | void> | moveFocusToButton: prevent focus returning to the target button. Default is true. | Hide the popout. Returns a promise that resolves to a `TransitionEvent` when the popout's hide animation ends or is cancelled. If the popout is already closed, the promise resolves immediately with `undefined`. |
| Event | Detail Type | Description |
|---|---|---|
open | NordEvent | Dispatched when the popout is opened. |
close | NordEvent | Dispatched when the popout is closed. |
This component has no CSS custom properties.
Usage
This section includes guidelines for designers and developers about the usage of this component in different contexts.
Do
- Always position popout next to the button or other interface element that toggles it.
- Use a popout to contain controls or information that doesn’t need to be shown immediately.
- Use a popout to contain items that will most likely not fit into the current view.
- Use a clearly labelled button to reveal the popout.
- Use the appropriate
aria-haspopupandroleattributes for both the toggle button and containing items. Please refer to the MDN documentation on both role values and child role values.
Don’t
- Don't hide information inside a popout that is imperative to using the current view.
- Don't obscure other controls that are important with the popout.
- Don't allow the popout to be obscured by other controls or the outer bounds of the current view.
- Don't use
always-floatingproperty for long lists or complex content that benefits from full-screen focus.
Content guidelines
If a popout contains actions, they should be always written in sentence case, not title case. The first word should be capitalized and the rest lowercase (unless a proper noun):
Popout actions 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 popout actions, such as “the”, “an” or “a”:
Avoid ending popout actions in punctuation:
Avoid all caps for popout actions:
Additional considerations
- The popout component is a containing component, only providing a way to reveal and hide controls by using a single button.
- Consider using the
alwaysFloatingproperty for compact interactions like simple filters or dropdown menus.
Integration
For integration guidelines, please see Web Components documentation .