Usage
Navigation is the vertical sidebar for moving around an app. It holds Nav Item links, optionally clustered into a Nav Group, with a header and footer slot for branding and account controls. A Nav Toggle collapses and expands the sidebar on small screens.
Import the parts you need — each import registers its custom element:
import "@nordhealth/components/lib/Navigation"
import "@nordhealth/components/lib/NavItem"
import "@nordhealth/components/lib/NavGroup"
import "@nordhealth/components/lib/NavToggle"
Then list your navigation items:
Composition
Navigation contains nav items, optionally organised into groups, with header and footer slots.
Navigation
├── (slot="header")
├── NavItem
├── NavGroup
│ └── NavItem
└── (slot="footer")
<nord-navigation>
<nord-nav-item href="#" icon="interface-dashboard">Dashboard</nord-nav-item>
<nord-nav-group>
<nord-nav-item href="#">Settings</nord-nav-item>
</nord-nav-group>
</nord-navigation>
Navigation
Navigation is the sidebar container. Use its header and footer slots for branding and account controls, and sticky-footer to pin the footer to the bottom.
Nav Item
Nav Item is a single link. Give it an href, an optional icon, and mark the current page with active.
Nav Group
Nav Group clusters related nav items together so a section can be scanned — and collapsed — as a unit.
Nav Toggle
Nav Toggle is the control that collapses and expands the navigation on small screens.
Examples
Grouped items
Cluster related links with a Nav Group.
Basic
A flat list of Nav Item links, the simplest useful navigation.
Complex
Combine groups, icons and header and footer slots for a full application sidebar.
Initially open group
Expand a Nav Group by default so its items are visible on first load.
Sticky footer
Use sticky-footer to pin the footer slot to the bottom of the sidebar regardless of how many items it holds, shown here within a full app shell.
RTL
Navigation follows the document or container direction. Toggle the direction to see the layout mirror.
Accessibility
- Each Nav Item is a real link — use an
hrefso it behaves like one — and mark the current page withactiveso its state is conveyed. - Use Nav Group to give long lists of links a clear, scannable structure.
- Provide a Nav Toggle so the navigation can be collapsed on small screens without losing access to it.
Templates
See this component composed into complete application views:
API reference
Navigation
Navigation is used to display the primary navigation in the sidebar of an application. Navigation includes a list of links that users use to move between sections of the application.
<nord-accordion></nord-accordion>Props
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
stickyFooter | sticky-footer | Controls whether the navigations's footer has sticky positioning. | boolean | false |
autoDismissOnSelect | auto-dismiss-on-select | Opt-in: when set, any open rail-mode subnav flyout in this navigation closes automatically once one of its leaf items is activated (for example, when a user clicks a link inside a flyout). Off by default — existing flyout behavior is unchanged unless this attribute is present. | boolean | false |
Slots
| Slot name | Description |
|---|---|
Default slot | The main section of the sidebar, for holding nav components. |
header | The top section of the sidebar. |
footer | The bottom section of the sidebar. |
| Event | Detail Type | Description |
|---|---|---|
toggle | NordEvent | Dispatched whenever a nav item's state changes between open and closed. |
activate | NordEvent | Dispatched whenever a nav item has been marked as active |
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-navigation-background-color | Controls the background color of the navigation element. | var(--n-color-nav-surface) |
--n-navigation-scroll-shadow-color-start | Color of the scroll-affordance shadow shown at the top of the scroll area (below the header) when sticky-footer is set. Set to transparent to disable. | rgb(0, 0, 0, 0.1) |
--n-navigation-scroll-shadow-color-end | Color of the scroll-affordance shadow shown at the bottom of the scroll area (above the footer) when sticky-footer is set. Set to transparent to disable. | rgb(0, 0, 0, 0.1) |
--n-navigation-scroll-mask | mask-image applied to the scrollable area when sticky-footer is set. Use with the shadow colors set to transparent to replace the dark scroll-shadow with a soft content fade at the edges. Example: linear-gradient(to bottom, transparent 0, black 24px, black calc(100% - 24px), transparent 100%). | none |
--n-navigation-padding-block | Block-axis (top/bottom) padding of the <nav> element that wraps the slotted nav groups. | var(--n-space-m) |
--n-navigation-padding-inline | Inline-axis (start/end) padding of the <nav> element that wraps the slotted nav groups. | var(--n-space-m) |
--n-navigation-footer-padding-block | Block-axis (top/bottom) padding inside the footer slot when sticky-footer is set. Has no visual effect when the footer slot is empty (slot is hidden in that case). | var(--n-space-s) |
--n-navigation-footer-padding-inline | Inline-axis (start/end) padding inside the footer slot when sticky-footer is set. Defaults to --n-navigation-padding-inline so the footer aligns with the nav content unless overridden. Has no visual effect when the footer slot is empty. | var(--n-navigation-padding-inline) |
Parts
This component is made up of the following parts.
Nav Group
Navigation group includes all the actions or items in a single group and is used for grouping items into related categories.
<nord-accordion-header></nord-accordion-header>Props
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
heading | heading | Heading and accessible label for the nav group | string | undefined | — |
Slots
| Slot name | Description |
|---|---|
Default slot | The default slot used for the nav items. |
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-nav-group-heading-display | Controls the display of the group's heading. Set to none to hide it — useful for a slot="subnav" group whose heading repeats the parent item's label inline; the heading is still shown in the rail flyout where it titles the projected list. | block |
Nav Item
Navigation item populates sidebar navigation with links. Every item should be placed inside a navigation group.
<nord-accordion-item></nord-accordion-item>Props
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
active | active | Used for indicating the current page. This gives a prominent background to the nav item, and marks the item as the current page for assistive technology. | boolean | false |
icon | icon | The name of an icon from Nordicons to display for the nav item. | string | undefined | — |
href | href | The url the nav item should link to. Note: this is not used if you have nested navigation using the "subnav" slot. | string | undefined | — |
badge | badge | Allows you to add a notification badge with a number next to the nav item. | string | undefined | — |
open | open | When the nav items contains a subnav, controls whether the section is expanded or not. Note: this is only used if you have nested navigation using the "subnav" slot. | boolean | false |
autoDismissOnSelect | auto-dismiss-on-select | Opt-in: when set, the item's rail-mode subnav flyout closes automatically once one of its leaf descendants is activated (for example, when a user clicks a link inside the flyout). Off by default — existing flyout behavior is unchanged unless this attribute is present. | boolean | false |
sideOffset | side-offset | Distance in pixels between the rail-mode tooltip and the item, forwarded
to the internal Tooltip's side-offset (the
Floating UI offset main axis). When unset, the tooltip's own default
(8) applies. Useful for lining up rail-item tooltips with neighbouring
standalone tooltips. | number | undefined | — |
alignOffset | align-offset | Offset in pixels along the alignment axis for the rail-mode tooltip,
forwarded to the internal Tooltip's
align-offset. When unset, the tooltip's own default (0) applies. | number | undefined | — |
Slots
| Slot name | Description |
|---|---|
Default slot | The default slot used for the nav item's text. |
icon | Slot for a custom leading icon element. Use when the icon attribute isn't enough — for example, an icon wrapped in a styled badge or circular frame. When set, it takes priority over the icon attribute and is shown in both the expanded nav and the collapsed rail. |
end | Trailing content rendered after the label inside the item's flex row. The slotted element flows naturally — it claims its real width and the label flex-shrinks to make room. Use for a custom badge, count pill, action icon, etc. when the badge attribute's plain text isn't enough. |
subnav | Used for nesting navigation. When used the nav-item becomes a button to collapse the subnav, rather than a link. |
rail-tooltip | Full content of the rail-mode tooltip. When provided, it replaces the default label projection — write the tooltip's content directly (label + count + keyboard shortcut etc., bound to whatever reactive state you like). When absent, the tooltip falls back to the item's default-slot label. Only rendered in rail mode. |
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-nav-item-color | Text color in the default state. | var(--n-color-text-weak) |
--n-nav-item-background | Background color in the default state. | transparent |
--n-nav-item-border-radius | Border radius of the item and its active-parent overlay. | var(--n-border-radius-s) |
--n-nav-item-padding-block | Block-axis (top/bottom) padding. | var(--n-space-s) |
--n-nav-item-padding-inline | Inline-axis (start/end) padding. | var(--n-space-s) |
--n-nav-item-line-height | Line height of the item's text. | var(--n-line-height-tight) |
--n-nav-item-icon-gap | Inline gap between the leading icon (the icon attribute or icon slot) and the item's text. | calc(var(--n-space-s) * 1.4) |
--n-nav-item-color-hover | Text color on hover. | var(--n-color-text) |
--n-nav-item-background-hover | Background color on hover. | var(--n-color-nav-hover) |
--n-nav-item-color-active | Text color when the item is active. | var(--n-color-text-on-accent) |
--n-nav-item-background-active | Background color when the item is active. | var(--n-color-accent) |
--n-nav-item-color-expanded | Text color when the item is an active parent (its subnav is expanded). | var(--n-color-text-weak) |
--n-nav-item-background-expanded | Background color of the overlay drawn behind an active-parent item. | var(--n-color-accent) |
--n-nav-item-expanded-overlay-opacity | Opacity of the active-parent overlay. Set to 1 for a solid background. | 0.12 |
--n-nav-item-expanded-overlay-filter | Filter applied to the active-parent overlay. Set to none to disable. | brightness(150%) |
--n-rail-flyout-background | Background colour of the rail-mode subnav flyout container. | var(--n-color-surface) |
--n-rail-flyout-box-shadow | Box-shadow of the rail-mode subnav flyout container. | var(--n-box-shadow-popout) |
--n-rail-flyout-min-inline-size | Minimum inline size (width in LTR) of the rail-mode subnav flyout body. | 220px |
--n-rail-flyout-padding | Padding of the rail-mode subnav flyout body. | var(--n-space-s) |
--n-rail-flyout-offset-inline | Extra inline-axis offset applied to the rail flyout (positive values push it away from the rail in LTR; mirrored in RTL). | 0 |
--n-rail-flyout-offset-block | Extra block-axis offset applied to the rail flyout (positive values push it downward). | 0 |
--n-rail-subnav-indicator-color | Colour of the small triangle indicator drawn in the bottom-inline-end corner of rail items that have a subnav (default + hover state). | var(--n-color-border-strong) |
--n-rail-subnav-indicator-color-active | Colour of the triangle indicator while the item's flyout popout is open. | var(--n-color-border-hover) |
--n-nav-badge-background | Background colour of the built-in badge attribute pill (.n-nav-badge). | var(--n-color-status-notification) |
--n-nav-badge-color | Text colour of the built-in badge attribute pill. | #fff |
--n-nav-badge-font-size | Font size of the built-in badge attribute pill. | var(--n-font-size-xs) |
--n-nav-badge-font-weight | Font weight of the built-in badge attribute pill. | var(--n-font-weight) |
--n-nav-badge-line-height | Line height of the built-in badge attribute pill. Combined with --n-nav-badge-padding-block this controls the pill's effective block size. | 1 |
--n-nav-badge-padding-block | Block-axis padding of the built-in badge attribute pill. | var(--n-space-xs) |
--n-nav-badge-padding-inline | Inline-axis padding of the built-in badge attribute pill. | calc(var(--n-space-s) / 2) |
--n-nav-badge-border-radius | Border radius of the built-in badge attribute pill. | var(--n-border-radius-pill) |
--n-nav-badge-min-inline-size | Minimum inline size (width in LTR) of the built-in badge attribute pill — sets a visual floor for single-digit counts. | 20px |
--n-nav-badge-margin-inline-start | Inline-start margin separating the badge from the preceding label inside the nav-item's flex row. | var(--n-space-xs) |
--n-rail-badge-size | Diameter of the rail-mode dot the badge collapses into when the layout is in collapse-mode="rail" and not nav-open. | 5px |
Nav Toggle
Nav toggle hides and shows the primary navigation inside <nord-layout>.
<nord-accordion-panel></nord-accordion-panel>Props
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
icon | icon | Icon shown in the resting state. Accepts any registered icon name.
Defaults to navigation-toggle. | string | — |
iconActive | icon-active | Icon shown on hover/focus (≥ 768px), swapping in for icon.
Defaults to navigation-toggle-lock. | string | — |
autoHide | auto-hide | When set, the toggle finds its ancestor <nord-layout> and hides
itself on wide viewports while the layout's nav is open. Useful when
placing the toggle outside the nav-toggle slot. | boolean | false |
square | square | Forwards the square attribute to the underlying <nord-button>,
giving the toggle a fixed square footprint instead of the default
pill shape. | boolean | false |
size | size | Size of the underlying <nord-button>. Defaults to m. | 's' | 'm' | 'm' |
iconSize | icon-size | Size of the inner <nord-icon> elements. Accepts the same values
as <nord-icon>'s size. Defaults to m. | 'xxs' | 'xs' | 's' | 'm' | 'l' | 'm' |
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. |
Design guidelinesFor designers
Usage
This section includes guidelines for designers and developers about the usage of this component in different contexts.
Do
- Use for primary navigation items that perform an action when clicked. Each action should navigate to a URL or trigger another action like a modal overlay.
- Group navigation items into navigation groups based on related categories.
- Use group headings to clarify the category of a section.
- Use icons for all top level navigation items.
Don’t
- Don’t place a
<nav>element inside the navigation component, as it already contains one internally.
Closing rail-mode flyouts on selection
When the layout is collapsed to a rail (collapse-mode="rail" with the nav closed), a parent navigation item opens its subnav in a flyout. Selecting a leaf link inside that flyout does not close it automatically, because the click happens inside the flyout's own overlay.
Call closeAllFlyouts() on <nord-navigation> to close every open flyout in the tree without reaching into component shadow DOM. Wire a single handler at the navigation root:
const navigation = document.querySelector('nord-navigation')
navigation.addEventListener('click', (event) => {
const leaf = event.target.closest('nord-nav-item[href]')
if (leaf) {
navigation.closeAllFlyouts()
}
})
Alternatively, set the auto-dismiss-on-select attribute on <nord-navigation> to close any open flyout automatically when a leaf item is activated:
<nord-navigation auto-dismiss-on-select>
<!-- nav items -->
</nord-navigation>
To close the flyout for a single item, call closeFlyout() on that <nord-nav-item> instead.
Content guidelines
When writing navigation item labels, always write them in sentence case, not title case. The first word should be capitalized and the rest lowercase (unless a proper noun):
Avoid unnecessary words and articles in item labels, such as “the”, “an” or “a”:
Avoid ending item labels in punctuation:
Use as few words as possible to describe each item label:
Avoid all caps for item labels and group titles: