HyTopbar

Usage examples on this page are written for Lit / plain HTML (<hy-topbar>). The same component ships as HyTopbar in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A responsive top navigation bar component for application headers.

The topbar provides a structured container for branding, navigation, and actions at the top of an application. It renders a semantic <header> element with role="banner" for proper accessibility.

Key Features

• Semantic <header> element with role="banner"
• Three-slot layout: start, default (center), end
• Fixed, sticky, or static positioning
• Responsive height with CSS custom properties
• Scroll-aware elevation and state changes
• Built-in skip link support for bypass blocks
• SSR compatible

Accessibility: built in

• Renders semantic <header role="banner"> element
• Skip link slot for bypass blocks
• Proper landmark for screen readers
• Focus management with visible focus indicators
• High contrast mode support
• Reduced motion support
• Sets scroll-padding-top on the document while fixed or sticky, so focused elements are not hidden behind the bar: the bar's rendered height (kept current by a ResizeObserver, so it follows the design system's surface heights and the height override) plus a 16px margin. It restores whatever inline value it replaced, and never clears a value it did not write

Accessibility: your part

• Put a skip link in the skip slot that points at the id of the main content.
• Mark the link to the current page: selected on a hy-link variant="navigation", active on a hy-tab-nav-item.

Mobile Navigation

The default slot content is hidden on mobile (< 768px) to accommodate responsive layouts. To ensure navigation remains accessible on mobile devices, either:

• Provide a hamburger menu in the start slot that reveals navigation
• Add the show-content-mobile attribute to keep the default slot visible

Browser Compatibility

• Modern browsers (Chrome, Firefox, Safari, Edge)
• SSR support via Lit's isServer

When to use

• The bar across the top of an application: the product's name, the page title, search and the account.
• Navigation of two or three destinations.

Do

• Keep it to what applies everywhere in the product.

When not to use

• More than a few destinations: a hy-sidebar, keeping the topbar for identity and global actions.
• Top-level destinations on a phone: hy-bottombar.
• Controls for one view only: a hy-toolbar in that view, or the actions-start / actions-end slots of its hy-tab-group.

Examples

Basic Usage

<hy-topbar label="Main navigation">
  <a slot="start" href="/">Logo</a>
  <nav>Navigation links</nav>
  <div slot="end">Actions</div>
</hy-topbar>

With Skip Link

<hy-topbar>
  <a slot="skip" href="#main-content" class="skip-link">Skip to content</a>
  <a slot="start" href="/">Logo</a>
  <nav>Links</nav>
</hy-topbar>
<main id="main-content">...</main>

Fixed Position with Elevation

<hy-topbar position="fixed" elevated>
  <span slot="start">Brand</span>
  <nav>Navigation</nav>
  <div slot="end">
    <button>Login</button>
  </div>
</hy-topbar>

Transparent Header

<hy-topbar transparent position="fixed">
  <a slot="start" href="/">Logo</a>
  <nav>Navigation</nav>
</hy-topbar>

API

Properties

Property	Attribute	Type	Default	Description
scrolled	scrolled	boolean	false	Whether the page has been scrolled past the threshold
position	position	'fixed' | 'sticky' | 'static'	'fixed'	CSS positioning of the topbar
size	size	'small' | 'medium' | 'large'	'medium'	Size variant controlling the topbar height, read from the design system's surface heights (--hy-surface-height-sm|md|lg, overridable per size). - small: dense tool UIs, admin dashboards - medium: standard applications - large: marketing sites, landing pages
height	height	string	''	Height override (escape hatch). Takes precedence over size.
elevated	elevated	boolean	false	Whether the topbar has elevation (shadow)
bordered	bordered	boolean	true	Whether the topbar has a bottom border
transparent	transparent	boolean	false	Whether the topbar has a transparent background
collapsed	collapsed	boolean	false	Whether the topbar is collapsed/hidden
label	label	string	'Site header'	Accessible name of the banner landmark. An empty value falls back to the default. Use for internationalization.
showContentMobile	show-content-mobile	boolean	false	Whether to show the default slot content on mobile devices

Events

Event	Detail	Description
scroll	—	Emitted when scroll state changes. Detail: { scrolled: boolean }

Slots

Slot	Description
skip	Skip link for keyboard users (bypass blocks)
start	Leading content (logo, hamburger menu)
default	Main/center content (navigation, title)
end	Trailing content (actions, user menu, search)

CSS Parts

Part	Description
base	The component's base wrapper element (the <header>)
container	The inner container for content alignment
start	The start section wrapper
content	The main/center content wrapper
end	The end section wrapper

CSS Custom Properties

The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.

Property	Default	Description
--hy-topbar-surface-height-sm	var(--hy-surface-height-sm)	Height for size="small"
--hy-topbar-surface-height-md	var(--hy-surface-height-md)	Height for size="medium"
--hy-topbar-surface-height-lg	var(--hy-surface-height-lg)	Height for size="large"
--hy-topbar-background-surface-elevation-3	var(--hy-background-surface-elevation-3)	Background color. (same as surface-base in light mode; lifts in dark mode for OLED-true-black visibility)
--hy-topbar-border-elevated-rest	var(--hy-border-elevated-rest)	Bottom border color (the rim of the floating bar)
--hy-topbar-foreground-default-rest	var(--hy-foreground-default-rest)	Text/foreground color
--hy-topbar-padding-shell-inline	var(--hy-padding-shell-inline)	Horizontal padding
--hy-topbar-gap-shell-inline	var(--hy-gap-shell-inline)	Gap between sections
--hy-topbar-padding-layout-sm	var(--hy-padding-layout-sm)	Skip link block padding
--hy-topbar-padding-layout-md	var(--hy-padding-layout-md)	Skip link inline padding
--hy-topbar-radius-form-md	var(--hy-radius-form-md)	Skip link border radius
--hy-topbar-shadow-elevation-3	var(--hy-shadow-elevation-3)	Box shadow when elevated or scrolled
--hy-topbar-stroke-sm	var(--hy-stroke-sm)	Border width for bordered variant
--hy-topbar-motion-transition-enter-duration	var(--hy-motion-transition-enter-duration)	Transition duration for the show and hide entrance animation
--hy-topbar-motion-transition-enter-easing	var(--hy-motion-transition-enter-easing)	Transition easing for the show and hide entrance animation