Espalier components → Header

import "@taprootio/espalier/header";

<esp-header>

Used to build the top navigation for a site. An empty header displays a bar. It has three slots for populating header content: topbar, brand, menu, and buttons.

The header works together with several companion components: <esp-menu> provides the navigation container, <esp-menu-item> renders individual links, and <esp-header-button> adds icon buttons for global actions.

Slots

<esp-header> has the following slots:

Optional utility row displayed above the primary header row. Combine with scroll-behavior="collapse-topbar" when the row should collapse after scroll.

brand

Place site brand here. Typically an anchor wrapping a logo SVG or image. When omitted, brand-logo, brand-text, and brand-href render a configured brand automatically. The brand container supports vertical alignment via --esp-header-brand-placement.

Place site navigation here. The menu slot should be populated with an <esp-menu> containing <esp-menu-item> children:

When there are too many <esp-menu-item>s on the screen, a burger button automatically appears that slides the full menu into view. Resize the screen to see the responsive behavior:

Published-site headers can be configured without custom brand markup. Pair layout, menu-display, theme-toggle, and scroll-behavior with esp-page header-position when the shell should stay fixed or sticky:

buttons

Place icon buttons for global actions here. The buttons slot should contain <esp-header-button> instances. Each button can reference the configured SVG sprite with icon and fires an esp-clicked event when activated:

Attributes

<esp-header> has the following attributes:

show-burger

show-burger has a default value of false.

Force the burger button to be visible regardless of the menu width. Use this when the burger controls an external element (e.g. a sidebar drawer) instead of the built-in <esp-menu> overlay.

layout

layout has a default value of "standard".

Header layout style.

standard places brand, menu, and actions on one row.
centered-brand centers the brand between left navigation and actions.
centered-menu keeps the brand at the start and actions at the end and centers the navigation on the bar between two equal columns.
extended puts navigation on a second row on wide screens.
extended-centered centers the brand and second-row navigation.
minimal keeps only brand/actions inline and uses the drawer menu.

brand-text

brand-text has a default value of "".

Configured brand text used when the brand slot is empty.

brand-logo

brand-logo has a default value of "".

Configured brand logo URL used when the brand slot is empty.

light-brand-logo

light-brand-logo has a default value of "".

Configured brand logo URL used in light scheme. A non-empty value overrides brand-logo; an empty value falls back to it.

dark-brand-logo

dark-brand-logo has a default value of "".

Configured brand logo URL used in dark scheme. A non-empty value overrides brand-logo; an empty value falls back to it.

brand-href

brand-href has a default value of "".

Optional brand link used by configured logo/text branding.

brand-alt

brand-alt has a default value of "".

Accessible text for a logo-only configured brand. When brand text is also present, the logo is decorative unless this is set.

brand-color

brand-color has a default value of "".

Optional configured brand color. Prefer theme fields for product-wide brand typography and this property for a local header override.

light-brand-color

light-brand-color has a default value of "".

Configured brand color used in light scheme. A non-empty value overrides brand-color; an empty value falls back to it and then --esp-header-brand-color.

dark-brand-color

dark-brand-color has a default value of "".

Configured brand color used in dark scheme. A non-empty value overrides brand-color; an empty value falls back to it and then --esp-header-brand-color.

brand-align

brand-align has a default value of "start".

Horizontal placement of the brand content inside its grid area.

brand-wrap

brand-wrap has a default value of "truncate".

Long-brand behavior for configured brand text.

menu-display has a default value of "auto".

Navigation display intent. auto tries inline navigation before using a drawer, drawer always uses the burger/drawer pattern, and inline leaves overflow handling to the slotted menu.

theme-toggle

theme-toggle has a default value of "hidden".

Whether the header renders its built-in light/dark toggle. Consumers can still provide their own control in the buttons slot when this is hidden.

scroll-behavior

scroll-behavior has a default value of "none".

Space-separated scroll behavior tokens. Supported tokens: compact, elevate, transparent, reveal, dock, collapse-topbar, and progress.

scroll-threshold

scroll-threshold has a default value of 16.

Scroll distance in pixels before scroll-reactive behavior applies.

dock-offset

dock-offset has a default value of 0.

Scroll distance in pixels before scroll-behavior="dock" applies. This is commonly set to the hero height when a transparent header should dock after the first section.

drawer-target

drawer-target has a default value of "".

Optional ID of an external drawer-capable menu controlled by the header burger. When set, burger open/close events call openDrawer() / closeDrawer() on that element instead of the menu slotted into the header.

full-bleed-content

full-bleed-content has a default value of false.

Opt out of surface alignment. When an esp-header is slotted into an esp-page, it constrains its bar content to the page's content surface by default (the bar background stays full-bleed). Set this to let the content span the full width instead, as it did before the page grew alignment modes. Standalone headers (outside esp-page) are already full-bleed and unaffected.

intent

intent has a default value of undefined.

The element's intent — its meaning: neutral (no pin), or success, warning, danger, info — each pinned to its fixed status family (blue for info), retunable per theme via intents. On token-emitting controls a non-neutral intent pins the filled-action pair to that family, derived over the governing zone's theme; class-styled chrome (badges, callouts, status pills) opts out of inline emission and renders its treatment from CSS classes instead. An intent never repaints the surrounding zone, which is what contexts are for. Removing the attribute restores the element's own default intent.

context

context has a default value of undefined.

A theme-defined color zone. The selected context rebinds designer-facing roles and emits a complete, contrast-enforced semantic token table on this host for descendants to inherit.

Methods

<esp-header> has the following methods:

traverseToClosest

Traverse up the DOM tree to find the closest element that matches the selector. This method is aware of shadow DOM boundaries and will traverse through them to find the element.

Events

<esp-header> emits the following events:

esp-header-theme-toggle

esp-header-theme-toggle is of type CustomEvent<EspThemeToggleEventDetail>.

Fired after the built-in theme toggle changes the nearest esp-root. Bubbles and crosses the shadow boundary.

CSS Properties

<esp-header> has the following CSS properties:

--esp-header-background

The background color of the header bar. Defaults to var(--esp-color-layer-2).

--esp-header-border-width

The border width of the header. Defaults to 0 0 1px 0.

--esp-header-border

The border style of the header. Defaults to solid var(--esp-color-border).

--esp-header-shadow

The box shadow of the header. Defaults to 0 0 2px var(--esp-color-shadow).

--esp-header-height

The height of the header bar. Defaults to calc(4.5 * var(--esp-size-small)).

--esp-header-color

The text/icon color inherited by header controls. Defaults to var(--esp-color-text).

--esp-header-z-index

The z-index of the header host. Defaults to 20.

--esp-header-content-max-width

Surface-alignment contract set by esp-page: the maximum width the bar content is constrained to (the bar background stays full-bleed). Defaults to 100% (no constraint). esp-page sets this to its resolved content cap.

--esp-header-content-lead

Surface-alignment contract set by esp-page: the fraction of the leftover width placed before the content, aligning it (0 = start, 0.5 = center, 1 = end). Defaults to 0.

--esp-header-compact-height

The height of compact scroll-reactive headers. Defaults to max(44px, calc(3.5 * var(--esp-size-small))).

--esp-header-extended-menu-height

The second-row menu height for extended layouts. Defaults to calc(3.5 * var(--esp-size-small)).

--esp-header-extended-menu-border

The border between the primary row and second-row menu in extended layouts. Defaults to 1px solid var(--esp-color-border).

--esp-header-topbar-height

The maximum height reserved for the optional topbar row. Defaults to 8rem.

The CSS place-content value for the brand container. Defaults to center.

The CSS justify-content value for the brand container. Defaults to start.

Inline padding for the brand container. Defaults to var(--esp-size-small).

The configured brand text/logo color. Defaults to var(--esp-color-headings).

The configured brand font family. Defaults through --esp-font-brand and --esp-font-headings to --esp-font-body.

The configured brand text size. Defaults to var(--esp-type-medium).

The configured brand font weight. Defaults to var(--esp-font-weight-brand, var(--esp-font-weight-headings)).

Space between a configured logo and brand text. Defaults to var(--esp-size-tiny-to-small).

The configured logo block size. Defaults to calc(0.72 * var(--esp-header-height, calc(4.5 * var(--esp-size-small)))).

The configured logo maximum inline size. Defaults to 12rem.

The maximum inline size of configured brand content. Defaults to min(36ch, 45vw).

The configured brand hover color. Defaults to var(--esp-color-headings-hover).

The configured brand hover background. Defaults to transparent.

The configured brand hover text decoration. Defaults to none.

The configured brand hover transform. Defaults to none.

--esp-header-transparent-background

Background used before scroll for transparent headers. Defaults to transparent.

--esp-header-transparent-color

Brand/action color used before scroll for transparent headers. Defaults to var(--esp-color-headings).

--esp-header-scrolled-shadow

Box shadow used by elevated scroll headers. Defaults to 0 2px 8px var(--esp-color-shadow).

--esp-header-progress-height

Height of the optional scroll progress bar. Defaults to 3px.

--esp-header-progress-background

Background color of the optional scroll progress bar. Defaults to var(--esp-color-link).

--esp-header-progress-track-background

Track background of the optional scroll progress bar. Defaults to transparent.

--esp-header-button-closed-color

The color of the burger button when the menu is closed. Defaults to var(--esp-color-headings).

--esp-header-button-closed-hover-color

The hover color of the burger button when the menu is closed. Defaults to var(--esp-color-headings-hover).

--esp-header-button-open-color

The color of the burger button when the menu is open. Defaults to var(--esp-color-text).

--esp-header-button-open-hover-color

The hover color of the burger button when the menu is open. Defaults to var(--esp-color-headings-hover).

--esp-header-button-stroke-width

The stroke width of the burger button lines. Defaults to 0.45rem.

--esp-field-background

Background color of the shared field shell. Defaults to var(--esp-color-layer-2).

--esp-field-border-color

Border color of the shared field shell. Defaults to var(--esp-color-border).

--esp-field-border-width

Border width of the shared field shell. Defaults to 1px.

--esp-field-text-color

Text color used inside the shared field shell. Defaults to var(--esp-color-text).

--esp-field-hover-bg

Hover background color of the shared field shell. Derived from --esp-field-background.

--esp-field-focus-bg

Focus background color of the shared field shell. Derived from --esp-field-background.

--esp-field-focus-shadow

Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).

Header