---
name: header-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit Header for
responsive site header composition with desktop/mobile sections, containers,
nav, nav items, actions, hamburger, active state, size, direction, and token
styling.
metadata:
component_version: "2.0.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux framework-consumer-integration app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: ""
contributor_sources: "libs/ui/src/organisms/header.tsx libs/ui/src/tokens/components/organisms/_header.css libs/ui/stories/organisms/header.stories.tsx"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit Header Usage
Use Header for global page header/navigation layout. Compose it with Link or
LinkButton for actual navigation items.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `Header`.
**Use it when**
- The global top bar: logo, primary navigation, search, account, cart.
**Use something else when**
| Need | Use instead |
| --- | --- |
| In-app admin navigation with many destinations | Sidebar + VerticalNavigation |
| Page-level title and actions | the page header inside content (title + top-right actions) |
**Do**
- Keep the same order across pages: logo start, navigation, search, account/cart end.
- Show cart count and account state; collapse navigation to a Drawer/Sidebar below `lg`.
- Make it sticky only if it stays compact; ensure it never covers focused content (scroll-padding).
**Don't**
- Put page-specific actions in the global header.
- Hide search behind an icon on desktop storefronts where search is a primary task.
**Copy and states**
- Navigation labels are short nouns; icon buttons have labels (`Cart, 3 items`, `Account`).
**Behaviour (from the UX spec)**
- `size` is density, not a breakpoint; the app decides where navigation collapses behind `Header.Hamburger`, and it is never just cut off.
- `Header.NavItem active` is visual only; also set `aria-current="page"` on the link. Pass a localised `aria-label` to `Header.Hamburger` (default `Toggle mobile menu`).
- The header is not a list of every feature; switching section never pretends to save an open draft.
**Figma → code**
| Figma | Code |
| --- | --- |
| `size=sm…lg` | same prop |
| — | `direction`, `Header.NavItem active`, `Header.Mobile position` (not in Figma) |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Organisms/Header → UX guidelines*.
## Setup
```tsx
Home{/* mobile nav */}
```
Supported props:
```text
Header size: sm | md | lg
direction: vertical | horizontal
Container position: start | center | end
Mobile position: left | right
NavItem active
parts: Desktop, Mobile, Container, Nav, NavItem, Actions, ActionItem, Hamburger
```
## Core Patterns
### Use Header.Hamburger for mobile menu state
Do not duplicate mobile state externally unless the current Header API cannot
support the UX.
### Put links/buttons inside slots
Header slots provide layout and token styling; Link/LinkButton/Button provide
navigation/action semantics.
### Use active on NavItem
Set `active` based on current route; do not style active nav with classes.
## Common Mistakes
### HIGH Raw responsive header
Wrong:
```tsx
```
Correct:
```tsx
```
Source: libs/ui/src/organisms/header.tsx
### HIGH Active nav styled inline
Wrong:
```tsx
Home
```
Correct:
```tsx
Home
```
Source: libs/ui/src/tokens/components/organisms/_header.css
### HIGH Native nav action instead of component
Wrong:
```tsx
Cart
```
Correct:
```tsx
Cart
```
## Validation Commands
```sh
rg -n "]*className=.*(font-|text-|bg-)" apps
rg -n "]*href=|]*size=\"(xs|xl)\"|position=\"(left|right)\".*Header\\.Container" apps
```
## Wave 2 contracts
Header.Desktop, Header.Mobile and Header.Hamburger use the header container’s content width (48rem breakpoint), not the viewport. Compose exactly one Mobile slot with its Hamburger. The trigger exposes aria-controls/aria-expanded; Escape closes an open menu and restores trigger focus. A custom Mobile id is synchronized with aria-controls. Canonical sizes are sm/md/lg (default md); place primary navigation inside the responsive slots.
Header.NavItem active controls styling only. Mark the actual current destination link with aria-current="page"; inactive destinations omit it.
Hamburger forwards Button props (including localized `aria-label`, event handlers and a React 19 `ref`). Prevent the click default to cancel toggling. On transition to desktop, the menu closes and focus moves to desktop navigation when the hidden mobile region held focus. Render Hamburger before Mobile so the next Tab enters the open navigation.
Rendering without `ResizeObserver` (jsdom tests, older embeds) no longer throws;
the initial measurement still runs.