Header « Layout Primitives

The top-level page header inside an <x-wirekit::app-shell>. It renders a 4rem-tall <header> element with a bottom border, elevated background, and horizontal padding — a natural anchor for brand, navigation, and profile slots.

Header is structural, not styled. It does not define its own menu, search, or notifications — those go inside as children via slots or composed WireKit components.

Basic Usage

Pass any content — brand, profile, search, buttons — as children. Use <x-wirekit::spacer> to push items apart.

Header with brand and profile

Acme

Jane Doe

<x-wirekit::header>
    <x-wirekit::brand name="Acme" />
    <x-wirekit::spacer />
    <x-wirekit::profile name="Jane Doe" />
</x-wirekit::header>

Set :sticky="true" to pin the header to the top of the viewport with position: sticky. The component uses the --z-wk-sticky token so the header stays above modals' backdrops but below actual dialogs.

Sticky header

Sticky Live

<x-wirekit::header :sticky="true">
    <x-wirekit::brand name="Sticky" />
    <x-wirekit::spacer />
    <x-wirekit::badge intent="success" surface="soft">Live</x-wirekit::badge>
</x-wirekit::header>

Container Layout

Set :container="true" to wrap the header's children inside a max-w-[--size-wk-container-2xl] centered inner div. The outer <header> still spans the viewport edge to edge (so the bottom border reaches the sides), while the content aligns with the main container grid.

Contained header with active nav link

Contained

Admin

<x-wirekit::header :container="true">
    <x-wirekit::brand name="Contained" />
    <x-wirekit::row wrap gap="lg" class="ml-auto">
        <nav style="display: flex; flex-wrap: wrap; gap: 1.25rem; align-items: center; font-size: var(--text-wk-sm);">
            <x-wirekit::link href="#" underline="hover" style="font-weight: 600;" aria-current="page">Projects</x-wirekit::link>
            <x-wirekit::link href="#" variant="muted" underline="hover">Team</x-wirekit::link>
            <x-wirekit::link href="#" variant="muted" underline="hover">Reports</x-wirekit::link>
        </nav>
        <x-wirekit::profile name="Admin" />
    </x-wirekit::row>
</x-wirekit::header>

A nav that outgrows one row belongs in navbar, not here header is a shell: it lays its slot children out in a wrapping row and has no opinion about what they are. That is deliberate, and it is also its limit — a nav with five or six items has no mobile answer here. It fits or it wraps, and which one happens depends on the font, so it can look fine in one place and break in another.

<x-wirekit::navbar> is the component that owns that problem. Below md it hides the item row and shows a hamburger; above it, the row. force-mobile renders the collapsed state at any width, which is how you check it without resizing.

Keep a header nav short enough that it cannot wrap, or use navbar.

The right-side cluster (nav + profile) is a <x-wirekit::row wrap class="ml-auto"> so the whole group hugs the container's right edge while the brand stays anchored to the left. ml-auto (margin-left: auto) is the canonical right-align idiom inside a flex container — it consumes all available free space to the left of the cluster without requiring any explicit width on the cluster itself. Every link in the nav (including "Settings") shares the same <x-wirekit::link underline="hover"> shape so the menu reads as a single typographic row; mixing in a <x-wirekit::button> would inflate "Settings" to button-size and break the row's vertical rhythm.

Nav-bar links override the link component's default underline="always" with underline="hover" so the underline only shows on hover. The active link uses aria-current="page" (semantic) plus a single visual treatment — bold weight at the same baseline as the other links. Adding a colored underline on top of the bold weight (or stacking the link's own underline beneath an inline border-bottom) double-marks the active state and lifts the label visually above the others. In a Livewire app the active state typically comes from the route name ({{ request()->routeIs('projects.*') ? 'font-semibold' : '' }}) rather than hardcoded styling.

Props

Prop	Type	Default	Description
`sticky`	`bool`	`false`	Pin the header to the top of the viewport with `position: sticky` and `z-index: var(--z-wk-sticky)`.
`container`	`bool`	`false`	Center the children inside `max-w-[--size-wk-container-2xl]`. The outer `<header>` still spans edge to edge.
`scope`	`string\|null`	`null`	Named personalization scope for block-level class overrides.

Accessibility

Rendered as a semantic <header> element — screen readers announce it as the banner landmark when it is a direct child of <body> or <app-shell>
sticky does not obscure keyboard focus: the focus outline remains visible for focusable descendants at every scroll position
No trap on Tab order — children participate normally in the page's tab sequence

Keyboard Interaction

This component is a layout wrapper. Keyboard interaction is delegated to its children.

Design Tokens

Token	Used for
`--color-wk-bg-elevated`	Header background
`--color-wk-border`	Bottom border
`--padding-wk-x-lg`	Horizontal padding
`--gap-wk-md`	Gap between children
`--z-wk-sticky`	`z-index` when `sticky` is set
`--size-wk-container-2xl`	Inner max width when `container` is set

Header

Basic Usage

Sticky Header

Container Layout

Props

Accessibility

Keyboard Interaction

Design Tokens

See Also

Was this page helpful?