SidebarItem handbook

License: Before reading component documentation, source, or npm usage instructions for the first time, read the full LICENSE. Reuse that review for the same task and version. Public API configuration and internal implementation changes have different license implications. All components use the unified runtime package; source rights remain governed by the license.

Overview

Present a navigation entry in Sidebar with active state, icon, hierarchy, and status hints so users can identify their location.

When to use it

Use it as a Sidebar navigation entry with a stable identity, icon, label, and destination. Active state does not perform application routing for you.

• Provide stable id and label; href is the navigation destination, and onSelect reports selection.

• disabled prevents navigation. actions adds item actions; parts configures built-in badges and action buttons.

• The built-in updated dot name follows LocaleProvider. The caller owns label, tags and actions. Existing decorative and accessibility-tree behavior in collapsed mode is unchanged.

Quick start

This example shows the recommended basic composition. See the sections below for more cases and composition limits.

<script lang="ts">	import { SidebarItem } from '@snowui-design-system/components';	let opened = $state('');</script> <div style="width: min(100%, 12rem);"><SidebarItem id="components" label="Components" icon="squares-four" iconCollection="phosphor" onSelect={() => opened = 'Components'} /></div>

API

See the base component documentation for inherited capabilities not redeclared here. This table lists only named public Props declared by this component.

Usage boundaries and details

API reference

Spacing between the main graphic, label, tags and updated hint stays at least 4 CSS px under root-font or gap scaling, preserving larger preferred gaps. Long labels truncate first, and both Link and Button respect available width. Trailing actions reserve independent space instead of covering status tags. The leading slot respects the built-in icon minimum of 12px; its default 20px geometry and hierarchy alignment are preserved.

With href, the main navigation content is a link; otherwise it is a button. Secondary actions are independent of the main navigation action. tags appear between label and the updated hint. The icon remains visible when collapsed, and a built-in Tooltip provides the full label. The component owns collapse transitions, label layout, and action placement; the page supplies data and application callbacks.

depth={1} denotes a second-level Item. Within the existing 20px leading slot, pseudo-elements draw an L-shaped dotted line with equal arms: dense 1px Black/40% dots, a 4px rounded bend, and a default visual length of 9px × 9px. Its vertical center aligns with the first-level Item icon above; its horizontal center aligns with the second-level Item label. The graphic expresses hierarchy only. It has no independent interaction or accessibility semantics, does not use icon resource resolution, and does not change with IconProvider. A second-level Item does not also show a regular icon. Callers should still hide second-level Items when Sidebar collapses.