HySidebar

Usage examples on this page are written for Lit / plain HTML (<hy-sidebar>). The same component ships as HySidebar 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 persistent navigation rail with collapse-to-icon-only state.

hy-sidebar is a single <nav> landmark — it does not wrap in <aside>, because <aside> is itself a complementary landmark and nesting the two would expose two landmarks for one purpose.

Pair with hy-sidebar-group for titled sections and hy-sidebar-item for rows. On mobile, wrap the sidebar inside hy-drawer — the drawer provides overlay/focus-trap semantics, the sidebar provides the content.

Examples

Navigation sidebar with grouped items

<hy-sidebar label="Main navigation">
  <div slot="header">Edelweiss</div>
  <hy-sidebar-group label="Workspace">
    <hy-sidebar-item value="dashboard" href="/dashboard" active>
      <hy-icon slot="leading" name="home" decorative></hy-icon>
      Dashboard
    </hy-sidebar-item>
    <hy-sidebar-item value="projects" href="/projects">
      <hy-icon slot="leading" name="folder" decorative></hy-icon>
      Projects
    </hy-sidebar-item>
  </hy-sidebar-group>
  <hy-sidebar-group label="Settings">
    <hy-sidebar-item value="preferences" href="/preferences">
      <hy-icon slot="leading" name="cog" decorative></hy-icon>
      Preferences
    </hy-sidebar-item>
  </hy-sidebar-group>
</hy-sidebar>

Collapsible rail with the built-in toggle

<hy-sidebar collapsible toggle-placement="header-end" width-expanded="280px">
  <div slot="header">Edelweiss</div>
  <hy-sidebar-item value="home" href="/">
    <hy-icon slot="leading" name="home" decorative></hy-icon>
    Home
  </hy-sidebar-item>
</hy-sidebar>
<script>
  document.querySelector('hy-sidebar').addEventListener('collapse', (e) => {
    console.log(e.detail.collapsed);
  });
</script>

API

Properties

Property	Attribute	Type	Default	Description
collapsed	collapsed	boolean	false	Whether the sidebar is collapsed to icon-only mode.
collapsible	collapsible	boolean	false	Whether to render a built-in collapse toggle at the top of the sidebar. The toggle is an hy-icon-button so its hit-area, hover/focus styling and theming follow the same scale as every other icon-button in the system (32px at size="small"). The icon name is hard-coded to arrow-collapse so consumers can't accidentally pass an undefined value — the historical foot-gun this slot was designed to avoid.
placement	placement	'start' | 'end'	'start'	Which edge of the parent the sidebar sits on.
togglePlacement	toggle-placement	'top-corner' | 'header-end'	'top-corner'	Where the built-in collapse toggle is placed. See SidebarTogglePlacement for the visual contract of each value. Default top-corner preserves pre-existing behavior; pick header-end when the brand mark is the visual anchor and the toggle should sit below it (Material 3 / modern SaaS pattern).
label	label	string	'Main navigation'	Accessible label for the <nav> landmark.
collapseLabel	collapse-label	string	'Collapse'	Label on the collapse toggle when the sidebar is expanded.
expandLabel	expand-label	string	'Expand'	Label on the collapse toggle when the sidebar is collapsed.
widthExpanded	width-expanded	string	''	Width when expanded. Escape hatch; writes --hy-sidebar-width-expanded inline.
widthCollapsed	width-collapsed	string	''	Width when collapsed. Escape hatch; writes --hy-sidebar-width-collapsed inline.

Events

Event	Detail	Description
collapse	—	Fired on every collapse state change. Detail: { collapsed: boolean }

Slots

Slot	Description
header	Logo, brand, or title above the nav. Stays visible when collapsed. Slot icon-only content (≈32px) that reads in the narrow rail. Position relative to the collapse toggle depends on togglePlacement — see that property for the visual contract.
default	Items and groups.
footer	Account, settings, version badge. Hidden chrome when empty.

CSS Parts

Part	Description
base	The <nav> landmark.
header	Header region.
content	Scrollable middle region containing items/groups.
footer	Footer region.
collapse-toggle	The built-in collapse toggle button (only rendered when collapsible).

CSS Custom Properties

Property	Description
--hy-sidebar-width-expanded	Width when expanded (default: 260px)
--hy-sidebar-width-collapsed	Width when collapsed (default: 64px)
--hy-sidebar-background	Background color (default: surface-base)
--hy-sidebar-border-color	Border color (default: border-default-rest)
--hy-sidebar-padding-block	Block padding for header/content/footer
--hy-sidebar-padding-inline	Inline padding for header/content/footer
--hy-sidebar-gap	Gap between items at the root
--hy-sidebar-transition-duration	Collapse transition duration
--hy-sidebar-control-inset	Distance from the top + inline-end corner to the absolute-positioned collapse toggle (default: padding-sm)
--hy-sidebar-collapsed	Host-scope variable exposing 1 (collapsed) or 0 (expanded) for descendant / consumer styling (read it via var(); nothing in Harmony consumes it yet)
--hy-sidebar-transition-easing	Easing for the collapse and expand transition

Methods

expand()

Expand the sidebar. No-op if already expanded.

collapse()

Collapse the sidebar. No-op if already collapsed.

toggle()

Toggle the collapsed state.