HyBottombar

Usage examples on this page are written for Lit / plain HTML (<hy-bottombar>). The same component ships as HyBottombar 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 bottom navigation bar component for mobile-style navigation.

The bottombar provides a structured container for navigation items at the bottom of an application, typically used for mobile navigation. It renders a semantic <nav> element with role="navigation" for proper accessibility.

Key Features

• Semantic <nav> element with role="navigation"
• Centered flexbox layout for navigation items
• Fixed, sticky, or static positioning
• Responsive height with CSS custom properties
• Built-in safe area inset support for notched devices
• SSR compatible

Accessibility: built in

• Renders semantic <nav role="navigation"> element
• Proper landmark for screen readers
• Focus management with visible focus indicators
• Sets scroll-padding-bottom 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 height, the height override and the safe-area inset) plus a fixed gap. It restores whatever inline value it replaced, and never clears a value it did not write — a static bar writes nothing
• Uses inert attribute when collapsed to remove from accessibility tree
• High contrast mode support
• Forced colors mode support (Windows High Contrast)
• Reduced motion support
• Hidden in print styles

Accessibility: your part

• Set aria-current="page" on the item for the screen being shown.
• Give every item an accessible name, even when only its icon is visible.

Browser Compatibility

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

When to use

• The three to five main destinations of an app on a phone.

Do

• Give every destination an icon and a short label.
• Keep the destinations in the same order on every screen.

When not to use

• Navigation on wide screens: hy-sidebar or hy-topbar; keep the bottom bar for narrow ones.
• More than five destinations: keep the most used ones and move the rest behind a More item that opens a hy-drawer.
• Switching views inside one screen: hy-tab-group.
• Switching a mode or setting: hy-toggle-group.
• The screen's main action: hy-fab.

Examples

Basic Usage

<hy-bottombar label="Main navigation">
  <hy-icon-button name="home" label="Home"></hy-icon-button>
  <hy-icon-button name="search" label="Search"></hy-icon-button>
  <hy-icon-button name="heart" label="Favorites"></hy-icon-button>
  <hy-icon-button name="lock" label="Account"></hy-icon-button>
</hy-bottombar>

Fixed Position with Elevation

<hy-bottombar position="fixed" elevated>
  <hy-icon-button name="home" label="Home"></hy-icon-button>
  <hy-icon-button name="search" label="Search"></hy-icon-button>
  <hy-icon-button name="info" label="Info"></hy-icon-button>
</hy-bottombar>

API

Properties

Property	Attribute	Type	Default	Description
position	position	'fixed' | 'sticky' | 'static'	'fixed'	CSS positioning of the bottombar
height	height	string	''	Height of the bottombar. Accepts any valid CSS value.
elevated	elevated	boolean	false	Whether the bottombar has elevation (shadow)
bordered	bordered	boolean	true	Whether the bottombar has a top border
collapsed	collapsed	boolean	false	Whether the bottombar is collapsed/hidden
label	label	string	'Bottom navigation'	Accessible name of the navigation landmark. An empty value falls back to the default. Use for internationalization.

Slots

Slot	Description
default	Navigation items (typically icon buttons)

CSS Parts

Part	Description
base	The component's base wrapper element (the <nav>)
container	The inner container for content alignment

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-bottombar-surface-height-md	var(--hy-surface-height-md)	Height of the bottombar
--hy-bottombar-background-surface-elevation-2	var(--hy-background-surface-elevation-2)	Background color. (same as surface-base in light mode; lifts in dark mode for OLED-true-black visibility)
--hy-bottombar-border-elevated-rest	var(--hy-border-elevated-rest)	Top border color (the rim of the floating bar)
--hy-bottombar-shadow-elevation-2-up	var(--hy-shadow-elevation-2-up)	Box shadow when elevated
--hy-bottombar-padding-shell-inline	var(--hy-padding-shell-inline)	Horizontal padding
--hy-bottombar-gap-shell-inline	var(--hy-gap-shell-inline)	Gap between items
--hy-bottombar-surface-width-xs	var(--hy-surface-width-xs)	Maximum width of each item
--hy-bottombar-stroke-sm	var(--hy-stroke-sm)	Border width for top border
--hy-bottombar-motion-transition-enter-duration	var(--hy-motion-transition-enter-duration)	Transition duration for the show and hide entrance animation
--hy-bottombar-motion-transition-enter-easing	var(--hy-motion-transition-enter-easing)	Transition easing for the show and hide entrance animation