HySidebarItem

Usage examples on this page are written for Lit / plain HTML (<hy-sidebar-item>). The same component ships as HySidebarItem 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 single row inside an hy-sidebar — icon, label, optional trailing content.

Renders as <a> when href is set and not disabled, otherwise <button>. disabled always wins — a disabled item is a <button disabled> regardless of href, because HTML has no native disabled attribute on anchors.

When the parent hy-sidebar is collapsed, the label hides visually but the accessible name survives via aria-label, and a tooltip mounts around the row using the same label text.

Examples

Link row with a leading icon and active state

<hy-sidebar-item value="dashboard" href="/dashboard" active>
  <hy-icon slot="leading" name="home" decorative></hy-icon>
  Dashboard
</hy-sidebar-item>

Button row with trailing content and client-side routing

<hy-sidebar-item value="inbox" href="/inbox">
  <hy-icon slot="leading" name="folder" decorative></hy-icon>
  Inbox
  <span slot="trailing">12</span>
</hy-sidebar-item>
<script>
  document.querySelector('hy-sidebar-item').addEventListener('activate', (e) => {
    e.detail.originalEvent.preventDefault(); // intercept, then route client-side
    console.log(e.detail.value, e.detail.href);
  });
</script>

API

Properties

Property	Attribute	Type	Default	Description
value	value	string	''	Identifier emitted in the activate event.
href	href	string	''	When set (and not disabled), the row renders as an <a>.
target	target	string	''	Anchor target; paired with href.
active	active	boolean	false	Active state. Sets aria-current="page" on the <a>.
disabled	disabled	boolean	false	Disabled state. Forces <button disabled> regardless of href.
label	label	string	''	Explicit accessible name. Overrides the auto-derived text from the default slot. Useful for i18n or when the visible label is not suitable for screen readers.
size	size	'small' | 'medium'	'medium'	Density variant. small tightens padding, drops the minimum 40px touch-target floor, and shifts typography down one step — matching hy-link size="small" for navigation-dense sidebars (docs TOC etc).

Events

Event	Detail	Description
activate	—	Fired on click (before navigation). Consumers with client-side routing can detail.originalEvent.preventDefault() to intercept. Detail: { value, href, originalEvent }

Slots

Slot	Description
leading	Optional icon. Reserved layout column only when content is present, or when the parent sidebar is collapsed (where the glyph is essentially required).
default	Label text.
trailing	Badge, count, or chevron. Column is hidden when the slot is empty.

CSS Parts

Part	Description
base	The interactive <a> or <button> element.
leading	Leading slot wrapper.
label	Label wrapper.
trailing	Trailing slot wrapper.

CSS Custom Properties

Property	Description
--hy-sidebar-item-gap	Gap between leading/label/trailing
--hy-sidebar-item-padding-block	Block padding
--hy-sidebar-item-padding-inline	Inline padding
--hy-sidebar-item-radius	Border radius
--hy-sidebar-item-icon-size	Leading/trailing icon size (default: 20px at medium, 16px at small)
--hy-sidebar-item-min-block-size	Minimum row height (default: touch target at medium, auto at small)
--hy-sidebar-item-background-rest	Background at rest
--hy-sidebar-item-background-hover	Background on hover
--hy-sidebar-item-background-active	Background when active
--hy-sidebar-item-foreground-rest	Text color at rest
--hy-sidebar-item-foreground-hover	Text color on hover
--hy-sidebar-item-foreground-active	Text color when active
--hy-sidebar-item-hover-duration	Transition duration for hover and focus state feedback
--hy-sidebar-item-hover-easing	Transition easing for hover and focus state feedback

Methods

focus()

Programmatically focus the underlying interactive element.