Header - National Design System

The site header shell combines the top bar and the main navigation into a single responsive region that handles government branding, primary page links, dropdown menus, and secondary utility actions across all screen sizes.

Header Structure

The header wraps three layers: the top bar for government branding and utilities, the main navigation bar, and the expandable DGA digital stamp panel.

Header Structure
header ├── div.nds-topbar.nds-content-wrapper │ ├── button.nds-digitalStamp-tab │ └── div.nds-topbar-info │ ├── div#nds-digitalStamp (expandable panel, hidden by default) │ └── div.nds-content-wrapper │ └── div.nds-digitalStamp-notices.nds-grid │ ├── div.nds-digitalStamp-card (notice cards) │ │ ├── div.nds-digitalStamp-icon │ │ └── div.nds-digitalStamp-content │ └── div.nds-digitalStamp-register │ └── nav.nds-main-nav.nds-content-wrapper └── div.nds-nav-container ├── a.nds-brand │ ├── img.nds-brand-logo │ └── span.nds-brand-name │ └── span.nds-brand-slogan ├── ul.nds-nav-minimal │ └── li.nds-mainNav-toggler (hamburger button) └── div.nds-collapse#ndsNavCollapse └── div.nds-collapse-content ├── ul.nds-nav-primary │ ├── li.nds-nav-item │ │ └── a.nds-nav-link │ ├── li.nds-nav-item.nds-dropdown │ │ ├── a.nds-nav-link │ │ └── div.nds-dropdown-menu │ │ └── div.nds-dropdown-content.nds-content-wrapper │ └── div.nds-show-more └── ul.nds-nav-actions └── li.nds-nav-item └── a/button.nds-nav-link

Navigation Bar

The sticky navigation bar holds branding, primary links, secondary actions, and the mobile hamburger toggle.

Navigation Bar

Dropdown Menu Content

Add nds-dropdown to a nav item to attach a dropdown panel. The panel's nds-dropdown-columns child supports three layouts for organizing content.

Column View — Categories with Titles
Row View — Flat Horizontal List
Multi-Column List — 3-Column Grid Inside a Column

Data-Driven Dropdowns

Pages that use the Jekyll-driven nav (see _data/mainnav/mainnav.yml) render dropdown content from two includes that map to the layouts above:

TemplateLayoutData Source
mainnav-column-view.htmlnds-colView with optional nds-multi-column-list per columncolumns + items array keyed to a file in _data/content/
mainnav-row-list.htmlnds-rowViewflat items array keyed to a file in _data/content/

Built-in Features

Auto-initialization

Activates when .nds-main-nav is on the page. Dropdowns, collapse, overflow detection, and scroll behavior attach automatically.

Responsive Collapse

Switches from a horizontal nav bar to a hamburger menu at a configurable breakpoint, with animated expand and collapse transitions.

Overflow Detection

Primary nav items that exceed the available width become scrollable, with a show-more button that scrolls through hidden items.

Dropdown Columns

Dropdown content can be organized in column, row, or multi-column list layouts that adapt to narrower screens.

Scroll-to-Anchor

Same-page anchor links in the nav close open menus and scroll smoothly to the target section.

Drag and Wheel Scrolling

Primary nav supports horizontal drag scrolling and converts vertical mouse wheel input to horizontal scroll when items overflow.

RTL Support

Scroll direction, drag behavior, and layout flip automatically in right-to-left contexts.

Reduced Motion

All header transitions respect the prefers-reduced-motion setting, skipping animations for users who have requested it.

Persistent Action Buttons

Nav items marked with nds-PAB automatically relocate to the minimal nav bar on small screens and return to their original position on larger viewports.

Backdrop Overlay

Opening a dropdown or the mobile collapse displays a backdrop that closes the menu on outside clicks, preventing interaction with page content beneath.

Usage Guidelines

Best Practices

  • Place the header at the top of every page. The top bar sits above the navigation bar, and both are rendered inside a <header> element.
  • Keep primary nav items between 3 and 8 links. Overflow handling activates automatically, but excessive items reduce usability.
  • Use dropdown menus for grouping related pages under a single primary nav item. Organize content into columns using nds-colView for category-based layouts or nds-rowView for flat lists.
  • Reserve the secondary nav for utility actions: search, language toggle, user profile, notifications. These persist across all breakpoints as icon-only buttons on smaller screens.
  • Use nds-CTA on a nav item to visually highlight a primary call-to-action button in the navigation bar.
  • Do not use the main navigation for in-page section links. Use Tabs for switching between content panels on the same page, or anchor links within the page body.
  • Do not place critical actions only inside dropdown menus. Users on mobile may not discover them. Promote key actions to the primary or secondary nav level.
  • Do not add more than one level of dropdown nesting. The component supports single-level dropdowns only.
  • Set the brand logo dimensions explicitly with width and height attributes to prevent layout shift during page load.
  • Use nds-icon-only on secondary nav items that should display as icon buttons. Labels are automatically hidden on smaller screens for non-CTA items.
  • Mark nav items that must remain visible at all breakpoints with nds-PAB. These items automatically move to the minimal nav bar on small screens and return to their original position on wider viewports.

Modifier Classes

ClassElementDescription
nds-dropdownnav-itemEnables dropdown menu behavior
nds-CTAnav-itemStyles the item as a call-to-action button
nds-icon-onlynav-itemDisplays as icon button, hides label
nds-PABnav-itemPersistent action button that relocates to the minimal nav bar on small screens
nds-show-morenav-itemMarks the overflow scroll button
nds-oncolornav-linkApplies on-color text styling for dark backgrounds
nds-menu-btnnav-linkTransparent background style with indicator for primary nav items (mobile)
nds-fitdropdown-menuSizes the dropdown to fit its content width
nds-colViewdropdown-columnsOrganizes content in vertical columns
nds-rowViewdropdown-columnsOrganizes content in a horizontal row layout
nds-multi-column-listlist inside dropdownRenders items in a 3-column grid

Data Attributes

AttributeElementDescription
data-state="current"nav-linkMarks the active page in the navigation

CSS Custom Properties

PropertyDefaultDescription
--nds-nav-height72pxHeight of the navigation bar
--nds-minimal-nav-bp960pxBreakpoint width for switching to mobile/minimal mode
--nds-transition-speed0.2Base transition speed in seconds
--nds-minimal-nav-item-height40pxHeight of each nav item in the mobile collapse panel

JavaScript API

The header initializes automatically when .nds-main-nav exists on the page. It is priority 1 in the loader (first to initialize). Toggle functions are exposed globally on window for use in HTML onclick attributes.

// ── Toggle Functions ───────────────────────── // All three are on `window` so they can be called // from inline onclick handlers or external scripts. // Toggle the mobile hamburger collapse. // Opens the collapse panel if closed, closes it if open. // Queues the action if an animation is already running. window.toggleNavbar(); // Toggle a dropdown menu. // Pass the native click event from the trigger element. // The function finds the closest .nds-dropdown ancestor, // closes any other open dropdown first, then opens the target. window.toggleDropdown(event); // ── Re-initialize ──────────────────────────── // Call after dynamically adding or removing nav items. // Re-runs layout calculations, overflow detection, // responsive breakpoint checks, and PAB placement. NDS.Mainnav.init(); // For top bar widget APIs (date, clock, weather, DGA stamp) // see the Top Bar documentation page.
Was this page useful?
60% of users said Yes from 2843 Feedbacks