Popout Updated
A small overlay that opens on demand to surface additional content and actions.
Usage
Popout is a small overlay that opens on demand, letting users reach additional content and actions without cluttering the page. It is ideal for filters, lightweight menus, and contextual panels.
A popout is wired to its trigger through id: give the popout an id, then point the triggering button's aria-controls at it and add aria-haspopup="true". The popout manages its own open and close behaviour from there.
import "@nordhealth/components/lib/Popout"
Place the trigger button and the popout together, linking them by id:
Examples
Position and alignment
The position attribute places the popout relative to its trigger: block-end (below), block-start (above), inline-start, inline-end, or auto to pick the side with the most room. The align attribute (start or end) shifts it along that edge.
Filter with checkboxes
A common use is a filter panel of Checkboxes with a clear action, opened from a filter button.
Always floating
By default the popout becomes a full-width sheet on small viewports. Add always-floating to keep it as a floating overlay at every viewport size.
Controlled mode New since Jun 24, 2026
By default the popout owns its open state: it finds the element whose aria-controls points at it and attaches its own click-to-toggle listener. This is ideal for simple triggers where the popout can manage everything itself.
When a wrapping component owns the open state — for example it exposes its own open property and drives the popout from its own trigger @click and show()/hide() calls — that built-in auto-wire becomes a second, competing toggle on the same click. Set the controlled attribute to opt out of it: the popout stays fully presentational (positioning, top layer, light dismiss, transitions, and aria-expanded mirroring all still work), but it no longer attaches its own toggle, leaving the component as the single owner of open.
In this example the button owns the open state and toggles the popout with show()/hide(); the popout's own auto-wire is off.
This is how the filter components and the Date Range Picker wrap Popout. You only need controlled when something other than the popout manages its open state; leave it off for standalone triggers.
Custom anchor
By default the popout anchors to its trigger. Set the anchor attribute to the id of another element to position the popout against that element instead.
Custom filter content
The popout is a generic container, so you can fill it with any custom filter UI rather than a plain checkbox list — for example a scrollable, searchable set of options with custom styling.
Tabs inside a popout
Compose interactive components inside the popout, such as a Tabs group, to organise richer content within a single overlay.
RTL
The popout follows the document or container direction, mirroring its alignment and inline positioning. Toggle the direction to see it flip.
Accessibility
- Link the popout to its trigger by setting
aria-controlson the button to the popout'sid, and addaria-haspopup="true"so assistive technology announces that the button opens a popout. - The popout can be dismissed by pressing Esc or clicking outside it, and focus returns to the trigger button when it closes.
- The popout escapes to the top layer via the Popover API, so it positions against the viewport and is not clipped by ancestors with
overflow: hidden,container-type, ortransform.
API reference
Popout
Popouts are small overlays that open on demand. They let users access additional content and actions without cluttering the page.
<nord-popout></nord-popout>Props
| 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 |
controlled | controlled | Set to true when the consuming component owns the open state and drives
the popout itself (e.g. via its own trigger @click and show()/hide()).
The popout stays presentational — positioning, top layer, light dismiss and
transitions all still work — but it does NOT attach its own click-to-toggle
listener to the aria-controls trigger, avoiding a competing second toggle
on the same click. | 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 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. |
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-popout-background | Background of the popout container. Set to transparent to suppress the popout's own surface (e.g. when a slotted element paints its own background). | var(--n-color-surface) |
--n-popout-box-shadow | Box-shadow of the popout container. Set to none to suppress the popout's own shadow. | var(--n-box-shadow-popout) |
Design guidelinesFor designers
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.