When to use it

Use HeaderSection first when the app wants the fast path for a complete storefront header.

Use Header when the app wants a shared fixed shell and needs lower-level control over the exact chrome anatomy.

Header fits branded storefronts where the useful variations are structural:

• different mobile and desktop action clusters
• different utility link treatments
• optional or branded mega-menu panels
• drawer footer content
• different logo, navigation, and action balance across brands

Composition model

Header is the lower-level composition shell beneath the newer section-first HeaderSection path.

Header is a shell with child regions:

• Header.Promotion — top strip region, often used with PromotionBar
• Header.Mobile — mobile-only shell region
• Header.Desktop — desktop-only shell region
• Header.Bar — main flex row container for each shell region
• Header.Group — flexible cluster wrapper
• Header.Logo — branded anchor region
• Header.Nav and Header.Link — navigation primitives, with keyed desktop panel controls via ownerKey, openPanelOnHover, closePanelOnHover, and closePanelOnClick
• Header.ActionButton — icon/text action buttons or links
• Header.MenuButton — menu trigger wired to the header’s internal drawer state
• Header.Panel — optional desktop panel region for mega menus or editorial nav content, keyed to the owning trigger with the same ownerKey
• Header.Drawer — mobile drawer wrapper tied to the same internal menu state

The root owns:

• fixed positioning
• transparent/default/overlay background behavior
• link color adaptation for overlay/transparent states
• internal mobile drawer open state used by Header.MenuButton and Header.Drawer
• internal desktop panel state used by Header.Link and Header.Panel

Behavior and theming guidance

Use variant="default" for solid chrome and variant="transparent" for hero-led pages where the header overlays the page opener until scroll.

Because the header stays fixed, the page body still needs to respect header height with top padding or a spacer.

For desktop mega-menu patterns, open the panel from the owning top-level Header.Link with openPanelOnHover and a stable ownerKey. Match that same ownerKey on the corresponding Header.Panel. Use closePanelOnHover on sibling or utility links so the panel collapses when focus moves away, and use closePanelOnClick on links inside the panel so the expanded header gets out of the way immediately after navigation.

If the app wants a slide-out menu, pair Header.MenuButton with Header.Drawer. The drawer content can include additional utility or branded content at the bottom.

Practical guidance

• Put navigation and utility structure in child slots
• Use Header.Panel for desktop-only mega-menu or editorial nav content
• Give each hover-owned desktop panel a stable ownerKey, and reuse that key on both the opening Header.Link and the matching Header.Panel
• Use Header.Link desktop panel controls to decide which top-level links open the mega menu and which links collapse it
• Add closePanelOnClick to mega-menu destination links so the header collapses as soon as navigation starts
• Use Header.Drawer for mobile navigation and auxiliary drawer content
• Keep PromotionBar as a separate component and decide explicitly whether it belongs inside Header.Promotion

If the app does not need a promotion strip or a desktop panel, simply omit those regions.