Usage
Layout is the application shell. It positions a navigation sidebar (nav slot), an optional header, top-bar, footer and drawer around the default slot, which holds the main content. It also manages the collapsible navigation and a built-in nav toggle.
import "@nordhealth/components/lib/Layout"
Examples
Navigation only
The minimum useful shell is a nav slot beside the main content.
Top bar
Place a Top Bar into the top-bar slot for a persistent header above the content.
Footer
Place a Footer into the footer slot, and set sticky-footer to keep it pinned to the bottom of the viewport.
Custom nav toggle
A <nord-nav-toggle> placed anywhere inside the layout (such as in a header) drives the nav. Set hide-default-nav-toggle to suppress the built-in fallback toggle.
Custom nav width
Set default-nav-width, min-nav-width and max-nav-width to control the resizable navigation sidebar.
Custom surface and background
Override --n-layout-background-color and --n-navigation-background-color to recolour the shell regions independently.
Drawer
Slot content into the drawer slot for a secondary panel alongside the main content.
Rail collapse
The navigation can collapse to a compact icon rail to reclaim horizontal space.
Full-height content
Let the main content fill the full viewport height, useful for scrollable panes and data tables.
No padding
Remove the default content padding for edge-to-edge layouts.
Custom nav toggle icons
Customise the open and closed icons used by the navigation toggle.
Theming
Apply a theme to the shell to recolour navigation, header and content together.
Advanced
A complete shell combining navigation, header, top bar, footer and main content.
RTL
Layout follows the document or container direction. Toggle the direction to see the shell mirror.
Accessibility
- Layout positions slotted regions but does not add landmark roles itself. Use semantic elements for each region — for example
<nord-header>/role="banner",<nord-navigation>/role="navigation", the main content, and<nord-footer>/role="contentinfo"— so assistive technology can navigate between them. - The built-in nav toggle is keyboard operable and the navigation can be opened and closed without a pointer. When supplying your own
<nord-nav-toggle>, keep it focusable and give icon-only toggles an accessible name. - On narrow viewports the navigation slides off-screen; ensure focus moves into the opened navigation and returns to the toggle on close so keyboard and screen reader users do not lose their place.
- The layout reflects the document or container direction, mirroring the sidebar and content for right-to-left languages.
Templates
See this component composed into complete application views:
API reference
Layout
Layout component is used to create the main layout of an app. Layout currently comes with one main configuration: two-column.
<nord-layout></nord-layout>Props
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
navOpen | nav-open | Controls whether the navigation is hidden off-screen or not.
Defaults to true for wide viewports, and false otherwise. | boolean | — |
persistNavState | persist-nav-state | Controls whether the navigation's open/closed state is persisted across page loads. This is useful for multi-page apps, where clicks on links trigger a full page load. | boolean | false |
syncNavState | sync-nav-state | Controls whether the navigation's open/closed state and width is synced across tabs/windows on the same origin. This is useful for long-lived app sessions where you may have multiple tabs/windows open at once. | boolean | false |
defaultNavWidth | default-nav-width | Initial width (in pixels) of the navigation sidebar when no value has been persisted. Changing this value between loads also re-seeds the persisted width for existing users, so design changes propagate without manual localStorage resets. | number | 250 |
minNavWidth | min-nav-width | Minimum width (in pixels) the navigation sidebar can be resized to via drag or keyboard. | number | 220 |
maxNavWidth | max-nav-width | Maximum width (in pixels) the navigation sidebar can be resized to via drag or keyboard. | number | 400 |
navRailWidth | nav-rail-width | Width (in pixels) of the rail column when collapse-mode="rail" is active
and the nav is closed. Default 64. | number | 64 |
padding | padding | Controls the padding of the default main section slot. When set to “none”, the nav and header slots will still have padding. | 'm' | 'none' | 'm' |
sticky | sticky | Controls whether the layout's header has sticky positioning. | boolean | false |
stickyFooter | sticky-footer | Controls whether the layout's footer has sticky positioning. | boolean | false |
hideDefaultNavToggle | hide-default-nav-toggle | Suppresses the built-in <nord-nav-toggle> rendered as the fallback for
the nav-toggle slot. Set this when you've placed your own
<nord-nav-toggle> elsewhere inside the layout (e.g. inside
<nord-header>) and want the layout's default one hidden. | boolean | false |
hideCollapseButton | hide-collapse-button | Suppresses the built-in collapse button rendered inside the nav (the
lock-icon button that toggles the sidebar between opened and the
collapsed state defined by collapse-mode). Set this when you've
placed your own collapse control elsewhere. | boolean | false |
toggleOnResizeClick | toggle-on-resize-click | When set, clicking the resize handle (without dragging) toggles the
nav between opened and the collapsed state defined by collapse-mode.
Dragging the handle still resizes the sidebar as usual; the click
behaviour only fires when the pointer barely moves between down and up. | boolean | false |
collapseMode | collapse-mode | Controls how the navigation renders when closed on wide viewports.
hide (default) slides the nav off-screen entirely. rail keeps a
narrow icon-only column visible, with tooltips for labels and flyout
popovers for items that have a subnav slot.
Narrow viewports always use the off-screen behaviour regardless of
this setting. | 'hide' | 'rail' | 'hide' |
Slots
| Slot name | Description |
|---|---|
Default slot | The default main section content. |
nav | Used to place content inside the navigation sidebar. |
top-bar | Used to place the Top Bar component. |
header | Used to place content inside the header section. This slot can be made sticky by utilizing the sticky property on the layout component. |
footer | Used to place content inside the footer section. This slot can be made sticky by utilizing the stickyFooter property on the layout component. |
drawer | Used to place additional content/details relating to a selected item. |
nav-toggle | Used to place a own nav-toggle component, for cases where you might need to add a tooltip. As an alternative, <nord-nav-toggle> can be placed anywhere inside <nord-layout> (e.g. inside a <nord-header>) — the layout listens for clicks and hover on any descendant <nord-nav-toggle> and drives toggle / peek behaviour accordingly. When using that placement, set hide-default-nav-toggle to suppress the layout's built-in fallback toggle. |
| Event | Detail Type | Description |
|---|---|---|
nav-open-change | NavOpenChangeEvent | Dispatched when the navigation open state changes, regardless of the trigger (user toggle, peek, focus, programmatic). The event's navOpen property contains the new state. |
nav-resize | NavResizeEvent | Dispatched when the navigation sidebar width changes. The event's width property contains the new width in pixels. |
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-layout-padding | Controls the padding around the main layout area (the main slot), using our spacing tokens. | var(--n-space-l) |
--n-layout-drawer-inline-size | Controls the width of the drawer area, when used. | 320px |
--n-layout-background-color | Controls the background color of the layout, using color tokens. | var(--n-color-background) |
--n-layout-nav-border-color | Controls the color of the border between the navigation and the main content area when the nav is open on wide screens. | var(--n-color-border) |
--n-layout-resize-color | Controls the colour of the resize handle's accent bar (shown on hover, focus, and while dragging). | var(--n-color-accent) |
--n-layout-resize-block-size | Controls the block-axis (vertical) size of the resize handle. Set to a fixed length (e.g. 200px) to constrain the handle so it doesn't span the full nav height. | 100% |
--n-layout-resize-inset-inline-end | Controls the inline-end offset of the resize handle's accent bar (the visible vertical line shown on hover/focus/drag). | 5px |
--n-layout-nav-rail-width | Controls the width of the navigation column when collapse-mode="rail" is active and the nav is closed. Equivalent to the nav-rail-width attribute / navRailWidth property; the CSS custom property takes precedence when set. | 64px |
--n-layout-header-size | Controls the block-axis (height) of the layout's header area. Also drives the size of the nav-toggle container and sticky-positioning offsets. | var(--n-space-xxl) |
--n-layout-drawer-box-shadow | Controls the box-shadow applied to the drawer (aside) on narrow viewports. | var(--n-box-shadow-nav) |
--n-layout-drawer-box-shadow-wide | Controls the box-shadow applied to the drawer (aside) on wide viewports (≥1240px). | var(--n-box-shadow-header) |
--n-layout-drawer-border-inline-start-width | Controls the inline-start border width of the drawer on wide viewports. | 1px |
--n-layout-drawer-border-inline-start-color | Controls the inline-start border color of the drawer on wide viewports. | var(--n-color-border) |
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-tooltip>
Tooltip
Tooltips are floating containers for displaying additional information for the currently focused element. A tooltip can be useful when you want to e.g. give a hint about an existing Command Menu shortcut.
Design guidelinesFor designers
Usage
This section includes guidelines for designers and developers about the usage of this component in different contexts.
Do
- To visually group content in a layout section, use the Card component.
- To lay out a set of smaller components, use the Stack component.
Don’t
- Never put layout component inside another HTML landmark.
- Don’t use when you need a vertical or horizontal layout system. Use Stack component instead.
Additional considerations
- Layout component uses
<main>element internally which is an HTML sectioning element which by default defines an ARIA landmark role. For that reason you should never put layout component inside another HTML landmark.
Theming
Please see the Accent color and Top Bar theming sections in our theming documentation for detailed guidelines.