Navbar
Horizontal navigation. Behavior is depth-driven: a flat list at one level, dropdown panels per top-level item when items have children. The mega flag turns the navbar into a megamenu with column layout and four optional content slots; mega_span selects whether the panel matches the navbar width (bar, default) or stretches edge-to-edge across the viewport (full).
Usage
When to use
- Primary site navigation in the page header on desktop
- Section-level navigation that benefits from horizontal scanning of top-level destinations
- Megamenu treatments where each top-level item opens a wide panel of grouped links and optional editorial content
When not to use
- Mobile navigation - use mobilenav inside a drawer
- Sidebar or documentation tree navigation - use sidenav
- A short, flat list of unrelated links - use linklist
Do
- Pick a single trigger model (click, hover, or hoverintent) per surface so behavior stays predictable
- Reserve the megamenu (
mega) for navigation with grouped sections and editorial content - Keep top-level items short and meaningful so they remain scannable across the bar
Don't
- Don't mix megamenu and plain dropdown behavior in the same navbar
- Don't go deeper than two levels - dropdown panels become hard to reach with keyboard or pointer
- Don't rely on hover alone - the click trigger remains keyboard accessible and is the safer default
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | array | - | Tree of navigation items. Each item has {url, text, description, is_current, is_active_trail, is_disabled, is_external, icon, badge, items, is_section, is_divider}. is_section applies inside a dropdown panel, where a heading has a column to head; the top-level bar renders links and dividers only. In mega mode each top-level item also accepts content_top, content_right, content_bottom, and content_left HTML strings. |
label | string | - | aria-label for the nav landmark. |
navbar_id | string | - | Unique id prefix for the panel and trigger elements. Auto-generated when absent. |
trigger | Enum: click, hover, hoverintent | click | How dropdown panels open. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.flat | Elevation | - | No elevation. |
.raised | Elevation | Yes | Slight elevation. |
.mega | Layout | - | Megamenu layout value. Renders top-level children as columns, optionally spanning the full viewport width. |
.mega-full | Layout | - | Megamenu layout value. Renders top-level children as columns, optionally spanning the full viewport width. |
Attributes
| Attribute | Set by | Required | Description |
|---|---|---|---|
data-navbar | Consumer | Yes | Marks the root nav element as a Semetrika navbar. The JS attaches the WAI-ARIA menubar keyboard pattern, aria-expanded sync, and close-on-focusout to this element. |
data-navbar-panel | Consumer | - | Identifies each dropdown panel inside the navbar. The JS sets up its toggle listener on every element carrying this attribute; CSS uses the same selector to flag mega-layout panels as the popover root. Panels MUST be a native popover (the twig template wires the popover and id attributes automatically). |
Examples
Sizes
The three size values, which scale the link font size and the link padding together.
Single level
Flat horizontal list with no dropdowns.
Dropdowns
Top-level items with children expose a dropdown panel anchored below the link. Levels three and deeper render indented inline inside the same dropdown.
Megamenu (bar span)
Top-level items render as columns inside a panel that matches the navbar width via CSS anchor positioning. The four content slots (content_top, content_right, content_bottom, content_left) wrap the tree.
Megamenu (full span)
Megamenu panel stretches edge-to-edge across the viewport regardless of where the navbar lives in the page.
Accessibility
- WCAG 2.2 AA
- Wrapped in
<nav>with an accessible name via thelabelarg oraria-label - Top-level triggers expose
aria-expandedandaria-controlsand are operable with keyboard alone - Click trigger uses light-dismiss so Escape and outside-click both close open panels
- Hoverintent uses motion only as enhancement; click and keyboard always work without it
- Reduced-motion preferences disable hover delays and panel transitions
Dependencies
- popout - positions dropdown panels
- hoverintent - debounces hover triggers when the
hoverintentmode is selected
Progressive enhancement
- No JS: native focus and keyboard navigation through links; without JS the click trigger does not open panels
- With JS: dropdown panels open on the chosen trigger (click, hover, or hoverintent), light-dismiss handles outside-click, and the megamenu panel matches the navbar width or stretches to the viewport edge per
mega_span - How to enable: include
navbar.jstogether with thehoverintentandpopoututility scripts