HySidebarGroup

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

Used inside <hy-sidebar> — it only means something as part of it.

A titled section inside hy-sidebar. Gives nav items a labeled boundary (role="group" + aria-labelledby) without any visual chrome beyond a caption.

With collapsible, the caption becomes a button that toggles a local expanded/collapsed state for the group. Independent from the parent sidebar's collapsed state — when the parent is collapsed, the caption hides visually, but the accessible name remains.

When not to use

• A handful of destinations: put the hy-sidebar-item rows straight in the hy-sidebar, with no group.
• The section that holds the main destinations: leave collapsible off so it never folds away.

Examples

Titled section inside a sidebar

<hy-sidebar-group label="Workspace">
  <hy-sidebar-item label="Dashboard" value="dashboard" href="/dashboard" active></hy-sidebar-item>
  <hy-sidebar-item label="Projects" value="projects" href="/projects"></hy-sidebar-item>
</hy-sidebar-group>

Collapsible group

<hy-sidebar-group label="Advanced" collapsible>
  <hy-sidebar-item label="Tokens" value="tokens" href="/tokens"></hy-sidebar-item>
  <hy-sidebar-item label="Audit" value="audit" href="/audit"></hy-sidebar-item>
</hy-sidebar-group>
<script>
  document.querySelector('hy-sidebar-group').addEventListener('toggle', (e) => {
    console.log(e.detail.expanded);
  });
</script>

Guide line

<hy-sidebar-group label="Semantic layer review" collapsible icon-placement="start" guide>
  <hy-sidebar-item label="Add paragraph spacing to body" value="485"></hy-sidebar-item>
  <hy-sidebar-item label="Add a List element under Typography" value="486"></hy-sidebar-item>
</hy-sidebar-group>

Guide line (guide). One straight vertical hairline alongside the group's items, so the rows read as belonging to the caption above — the docs-sidebar shape (shadcn SidebarMenuSub, VitePress, Starlight). It hangs from the chevron's center with icon-placement="start" (items move in so their labels line up with the caption text); otherwise from the caption's padding edge. It goes with the items when the group collapses and when the parent sidebar collapses to its rail. Decorative: nothing in the accessibility tree. Off by default — most systems draw none.

Current caption. While one of its items is active, the group paints its caption (and chevron) in brand ink, so the path to the selection reads in color — open or closed. Automatic, no attribute to set; the selected item itself carries aria-current.

API

Properties

Property	Attribute	Type	Default	Description
label	label	string	''	Caption text displayed above the items.
collapsible	collapsible	boolean	false	Whether the caption toggles expand/collapse for this group.
expanded	expanded	boolean	true	Expanded state. Only meaningful when collapsible.
iconPlacement	icon-placement	'end' | 'start' | 'none'	'end'	Where the expand chevron sits, or none for a caption with no glyph. Only meaningful when collapsible.
guide	guide	boolean	false	Draw a vertical guide line alongside the group's items.

Events

Event	Detail	Description
toggle	—	Only when collapsible. Detail: { expanded: boolean }

Slots

Slot	Description
default	Items to group.

CSS Parts

Part	Description
base	The <section> wrapper.
caption	The caption element (heading or button).
items	The items region.

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-sidebar-group-padding-layout-xs	var(--hy-padding-layout-xs)	Caption block padding
--hy-sidebar-group-padding-layout-sm	var(--hy-padding-layout-sm)	Caption inline padding
--hy-sidebar-group-foreground-subtle-rest	var(--hy-foreground-subtle-rest)	Caption text color
--hy-sidebar-group-foreground-brand-rest	var(--hy-foreground-brand-rest)	Caption text color while the group holds the current item
--hy-sidebar-group-label-sm-font-family	var(--hy-label-sm-font-family)	Caption font family
--hy-sidebar-group-label-sm-font-size	var(--hy-label-sm-font-size)	Caption font size
--hy-sidebar-group-label-sm-font-weight	var(--hy-label-sm-font-weight)	Caption font weight
--hy-sidebar-group-label-sm-line-height	var(--hy-label-sm-line-height)	Caption line height
--hy-sidebar-group-label-sm-letter-spacing	var(--hy-label-sm-letter-spacing)	Caption letter spacing
--hy-sidebar-group-caption-text-transform	none	Case of the caption (none unless set: shown as written; uppercase for capitals). Display only — the caption text stays as written.
--hy-sidebar-group-gap-row-nav-xs-block	var(--hy-gap-row-nav-xs-block)	Gap between the caption and its items
--hy-sidebar-group-items-gap-row-nav-xs-block	var(--hy-gap-row-nav-xs-block)	Gap between one item and the next
--hy-sidebar-group-icon-size-xs	var(--hy-icon-size-xs)	Expand chevron size (12px at standard density)
--hy-sidebar-group-gap-row-nav-sm-inline	var(--hy-gap-row-nav-sm-inline)	Gap between a start-placed chevron and the caption text
--hy-sidebar-group-stroke-sm	var(--hy-stroke-sm)	Width of the guide line
--hy-sidebar-group-border-subtle-rest	var(--hy-border-subtle-rest)	Color of the guide line
--hy-sidebar-group-motion-transition-expand-duration	var(--hy-motion-transition-expand-duration)	Transition duration for the group expand and collapse animation
--hy-sidebar-group-motion-transition-expand-easing	var(--hy-motion-transition-expand-easing)	Transition easing for the group expand and collapse animation