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 Features

• 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 CSS custom property to prevent focus obscuring

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

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. - small: 48px — dense tool UIs, admin dashboards - medium: 64px — standard applications - large: 112px — 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	''	Accessible label for the topbar
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

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