Navigation

Open in Storybook

A vertical sidebar of links and groups for moving around an app.

Overview

Usage

Composition

Examples

Accessibility

Templates

API reference

Parts

Design guidelines

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:

Copy code

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.

Copy code

Navigation
├── (slot="header")
├── NavItem
├── NavGroup
│   └── NavItem
└── (slot="footer")

Copy code

<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 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 href so it behaves like one — and mark the current page with active so 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:

Application Template

A classic application shell with a header, collapsible navigation and a main content area.

Ready

New App Shell Template

A complete application shell pairing the layout with an aside rail and drawers for secondary content.

Ready

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-navigation></nord-navigation>

Props

Property	Attribute	Description	Type	Default
`stickyFooter`	`sticky-footer`	Controls whether the navigations's footer has sticky positioning.	`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-nav-group></nord-nav-group>

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.

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-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-nav-item></nord-nav-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`

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.

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-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-nav-toggle></nord-nav-toggle>

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.

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):

My tasks

My Tasks

Avoid unnecessary words and articles in item labels, such as “the”, “an” or “a”:

Change theme

Change the theme

Avoid ending item labels in punctuation:

Switch user

Switch user.

Use as few words as possible to describe each item label:

Payments

Payments in your clinic

Avoid all caps for item labels and group titles:

Dashboard

DASHBOARD

Navigation

Templates

API reference

Navigation

Props

Slots

CSS Properties

Parts

Nav Group

Props

Slots

CSS Properties

Nav Item

Props

Slots

Methods

CSS Properties

Nav Toggle

Props

Methods

Usage

Content guidelines

Was this page helpful?