Header Nav
A batteries-included top app bar composed from the chrome bricks (esa-app-bar + esa-icon-link + esa-nav-dropdown): brand slot, data-driven primary nav with dropdowns, an actions slot, and a user menu. Disclosures are native details/summary, so it needs zero runtime JS. For full control, compose the bricks directly.
Preview
Open Reports or the avatar to expand the native disclosures.
<EsaHeaderNav items={items} user={user}>
<strong slot="brand">ESA</strong>
</EsaHeaderNav>States
Brand only, no signed-in user — the avatar / user menu is omitted when user is absent.
<EsaHeaderNav items={items}>
<strong slot="brand">Beacon</strong>
</EsaHeaderNav>API
| Prop | Type | Default | Description |
|---|---|---|---|
items | EsaHeaderNavItem[] | [] | Primary nav links. Each is { label; href?; icon?; children? }; an item with children renders a dropdown. |
user | EsaHeaderNavUser | — | Optional signed-in user { name; email?; avatarUrl?; initials? }. When present, renders the avatar + user menu. |
navLabel | string | 'Main' | Accessible name for the navigation landmark around the links. The links now sit in a real <nav> inside the banner; before 2026-08-18 they were loose in the header and the primary site navigation was not a landmark at all. |
Slots
| Prop | Type | Default | Description |
|---|---|---|---|
brand | slot | — | Left-aligned logo / wordmark area. |
actions | slot | — | Right-aligned controls placed before the user menu (e.g. search, notifications). |
Nav dropdowns and the user menu are native details/summary disclosures (via esa-nav-dropdown) — no JavaScript required.
Accessibility
- Each item with children renders an
esa-nav-dropdowndisclosure; plain items render anesa-icon-link. - Disclosures are native details/summary — keyboard toggling and the expanded state come for free.
- The avatar button carries an
aria-labelnaming the user (User menu for …). - Decorative chevrons and glyph SVGs are
aria-hidden.
Theming surface
Every public token this component reads, extracted from its source at build time,
split by blast radius: the hooks that belong to this component,
then the shared and system tokens it consumes alongside everything else. The
Resolves to column walks each token's real lineage —
component → semantic → primitive → raw value — so you
can see exactly where re-pointing it lands. A spoke re-skins by overriding these in
its theme-<slug>.css; component internals are never edited. No
hook for what you need? File it with /request-lego.
Type roles it names
This component does not set a size, weight, face or tracking of its own — it names a composite, and the composite carries all five. A composite is a class rather than a token, so none of it appears in the tables below; re-theme text by re-pointing the token family, not by editing the component.
| Role | Re-point | Reach |
|---|---|---|
.typography-body-md |
| +28 more componentsesa-app-shell, esa-breadcrumbs, esa-card, esa-checkbox, esa-checkbox-group, esa-collapsible, esa-combobox, esa-command-palette, esa-confirm-dialog, esa-container, esa-danger-zone, esa-dialog, esa-dropdown-menu, esa-empty-state, esa-entity-search, esa-form-field, esa-input-tag, esa-nav-dropdown, esa-page-header, esa-popover, esa-progress-bar, esa-radio-group, esa-select, esa-side-dialog, esa-snackbar-item, esa-switch-toggle, esa-tab-layout, esa-textarea |
.typography-body-xs |
| +14 more componentsesa-breadcrumbs, esa-checkbox, esa-checkbox-group, esa-combobox, esa-command-palette, esa-empty-state, esa-entity-search, esa-field-error, esa-input-tag, esa-progress-bar, esa-radio-group, esa-search-panel, esa-select, esa-textarea |
.typography-label-md |
| +33 more componentsesa-app-bar, esa-breadcrumbs, esa-button-group, esa-button-toggle, esa-card, esa-checkbox-group, esa-color-picker, esa-combobox, esa-command-palette, esa-confirm-dialog, esa-danger-zone, esa-date-picker, esa-dialog, esa-empty-state, esa-entity-search, esa-file-upload, esa-filter-container, esa-form-field, esa-input-tag, esa-link-column, esa-page-header, esa-pillbox, esa-popover, esa-progress-bar, esa-radio-group, esa-range-slider, esa-select, esa-side-dialog, esa-sidebar-nav, esa-stat, esa-text-field, esa-textarea, esa-tooltip |
.typography-label-md-strong |
| +3 more componentsesa-avatar, esa-empty-state, esa-error-summary |
Wired to this component
No other component reads these — re-point them and esa-header-nav is the
only thing that moves.
| Token | Tier | Resolves to |
|---|---|---|
--header-nav-avatar-size | component | 32px |
Shared tokens it reads
Owned by a family or by the semantic layer. Still overridable — but scope the
override (esa-foo { --form-border-color: … }) unless you mean to move
everything that reads it. Reach says what else that is.
| Token | Reach | Resolves to |
|---|---|---|
--focus-ring-color | component focus ring group · +34 more | #3e9b4f via --color-border-default-focus → --color-grass-10 |
--focus-ring-offset | component focus ring group · +31 more | 2px |
--focus-ring-width | component focus ring group · +35 more | 2px via --border-width-focus → --border-width-200 |
--border-width-default | semantic every component | 1px via --border-width-100 |
--color-background-brand | semantic every component | #46a758 via --color-grass-9 |
--color-background-elevation-raised | semantic every component | #fcfcfc via --color-gray-1 |
--color-background-elevation-sunken | semantic every component | #f0f0f0 via --color-gray-3 |
--color-border-default | semantic every component | one role per property, so a theme can move the ring's weight and its colour independently. Tier 3's --focus-ring-width now reads this instead of holding a bare 2px, which is the same shape --focus-ring-color has always had (a thin tier-3 alias over a tier-2 role) — width was simply never given the tier-2 half.
*
* This role was rejected once, and the rejection is worth recording because its PREMISE was wrong rather than its reasoning. The argument against an `emphasis` width was that every 2px border in the kit is micro-geometry — spinner rings, the kbd keycap lip, a chevron. The focus ring was not in that enumeration and does not fit it: 33 components render it, more than read any other tier-3 token, and it is not micro-geometry but an accessibility affordance whose weight is a legitimate brand axis (a spoke that needs a heavier ring for contrast has to be able to reach it). It is also not a `border` in any component — every consumer paints it with `outline` or `box-shadow` — which is precisely why a survey of BORDERS missed it. The name still says `border` because tier 2 already calls the ring's colour --color-border-default-focus |
--color-content-default | semantic every component | #202020 via --color-gray-12 |
--color-content-default-secondary | semantic every component | #646464 via --color-gray-11 |
--color-content-utility-danger | semantic every component | #ce2c31 via --color-red-11 |
--elevation-4 | semantic every component | 0 via --shadow-offset-x |
--radius-md | semantic every component | 0.5rem via --radius-200 |
--radius-sm | semantic every component | 0.25rem via --radius-100 |
--z-dropdown | semantic every component | 50 |
--font-size-100 | primitive every component | clamp(0.625rem, 0.56rem + 0.32vw, 0.75rem) |
--spacing-100 | primitive every component | 0.25rem |
--spacing-150 | primitive every component | 0.375rem |
--spacing-200 | primitive every component | 0.5rem |
--spacing-300 | primitive every component | 0.75rem |
--spacing-400 | primitive every component | 1rem |
--spacing-600 | primitive every component | 2rem |