HySidebarItem
Usage examples on this page are written for Lit / plain HTML (
<hy-sidebar-item>). The same component ships asHySidebarItemin@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 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.
When not to use
- An action that changes something without going to another page:
hy-button, not a sidebar row.
Examples
Link row with a leading icon and active state
html
<hy-sidebar-item label="Dashboard" value="dashboard" href="/dashboard" active>
<hy-icon slot="leading" name="home" decorative></hy-icon>
</hy-sidebar-item>Button row with trailing content and client-side routing
html
<hy-sidebar-item label="Inbox" value="inbox" href="/inbox">
<hy-icon slot="leading" name="folder" decorative></hy-icon>
<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>Section row: a link to the section that also opens its list
html
<hy-sidebar-item
label="Primitives"
variant="section"
value="primitives"
href="/tokens/primitives"
active
aria-expanded="true"
>
<hy-icon slot="leading" name="chevron-down" decorative></hy-icon>
</hy-sidebar-item>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 on the row (value from current). |
current | current | 'page' | 'true' | 'page' | The aria-current value an active row announces. Leave at page for a row whose href is the current URL; set true when the row is an in-page selection, so two rows in one nav never both claim page. |
disabled | disabled | boolean | false | Disabled state. Forces <button disabled> regardless of href. |
label | label | string | '' | The row's text — the name of the page it leads to; the tooltip and aria-label of a collapsed row. |
size | size | 'small' | 'medium' | 'medium' | Density variant. small tightens padding and shifts typography down one step — matching hy-link size="small" for navigation-dense sidebars (docs TOC etc). Neither size has a height floor with a fine pointer; both floor at the small touch target on a coarse one. |
variant | variant | 'default' | 'section' | 'default' | section makes the row the head of a section of the nav — a link to the section that also opens its list (with aria-expanded), the Spectrum multilevel side-nav shape. The current one is marked by its brand ink instead of the selection fill, it hovers like its siblings, and its leading box fits a chevron (put an hy-icon name="chevron-down" in leading). Its text keeps the item's type; a consumer that wants the row in a heading style sets the font hooks. default is the ordinary row. |
ariaExpanded | aria-expanded | 'true' | 'false' | null | The row also discloses something — a section row whose list it folds. 'true' / 'false' is forwarded as aria-expanded on the inner link or button (a link may carry it: it still navigates, and says whether what it opens is open); null (default) for a plain row. As hy-link's. |
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). |
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
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-item-gap-row-nav-md-inline | var(--hy-gap-row-nav-md-inline) | Gap between leading/label/trailing |
--hy-sidebar-item-gap-row-nav-xs-inline | var(--hy-gap-row-nav-xs-inline) | Gap between leading/label/trailing |
--hy-sidebar-item-padding-row-nav-sm-block | var(--hy-padding-row-nav-sm-block) | Block padding |
--hy-sidebar-item-padding-row-nav-xs-block | var(--hy-padding-row-nav-xs-block) | Block padding |
--hy-sidebar-item-padding-row-nav-sm-inline | var(--hy-padding-row-nav-sm-inline) | Inline padding (both sizes) |
--hy-sidebar-item-radius-row-nav-sm | var(--hy-radius-row-nav-sm) | Border radius |
--hy-sidebar-item-icon-size | — | Leading/trailing icon size (default: 20px at medium, 16px at small) |
--hy-sidebar-item-icon-size-xs | var(--hy-icon-size-xs) | Leading/trailing icon size of a section row (the chevron's box) |
--hy-sidebar-item-body-md-font-family | var(--hy-body-md-font-family) | Label font family (default: the size's label family) |
--hy-sidebar-item-body-sm-font-family | var(--hy-body-sm-font-family) | Label font family (default: the size's label family) |
--hy-sidebar-item-body-md-font-size | var(--hy-body-md-font-size) | Label font size (default: the size's label size) |
--hy-sidebar-item-body-sm-font-size | var(--hy-body-sm-font-size) | Label font size (default: the size's label size) |
--hy-sidebar-item-body-md-font-weight | var(--hy-body-md-font-weight) | Label font weight (default: the size's label weight) |
--hy-sidebar-item-body-sm-font-weight | var(--hy-body-sm-font-weight) | Label font weight (default: the size's label weight) |
--hy-sidebar-item-body-md-line-height | var(--hy-body-md-line-height) | Label line height (default: the size's label line height) |
--hy-sidebar-item-body-sm-line-height | var(--hy-body-sm-line-height) | Label line height (default: the size's label line height) |
--hy-sidebar-item-body-md-letter-spacing | var(--hy-body-md-letter-spacing) | Label letter spacing (default: the size's label letter spacing) |
--hy-sidebar-item-body-sm-letter-spacing | var(--hy-body-sm-letter-spacing) | Label letter spacing (default: the size's label letter spacing) |
--hy-sidebar-item-background-rest | transparent | Background at rest |
--hy-sidebar-item-background-neutral-hover | var(--hy-background-neutral-hover) | Background on hover |
--hy-sidebar-item-background-selection-rest | var(--hy-background-selection-rest) | Background when active |
--hy-sidebar-item-background-selection-hover | var(--hy-background-selection-hover) | Background on hover when active |
--hy-sidebar-item-foreground-default-rest | var(--hy-foreground-default-rest) | Text color at rest and when active |
--hy-sidebar-item-foreground-brand-rest | var(--hy-foreground-brand-rest) | Text color of the current section row |
--hy-sidebar-item-foreground-default-hover | var(--hy-foreground-default-hover) | Text color on hover |
--hy-sidebar-item-foreground-icon-default-disabled | var(--hy-foreground-icon-default-disabled) | The slotted icons' color when the row is disabled |
--hy-sidebar-item-motion-transition-hover-duration | var(--hy-motion-transition-hover-duration) | Transition duration for hover and focus state feedback |
--hy-sidebar-item-motion-transition-hover-easing | var(--hy-motion-transition-hover-easing) | Transition easing for hover and focus state feedback |
Methods
focus()
Programmatically focus the underlying interactive element.