ki-sidebar
@kimen/elements/ki-sidebar- Source
- Agent reference
Use Sidebar when an application has more than five destinations or groups its destinations. Use top navigation for a few sections, and a drawer or mobile navigation at narrow widths.
<ki-sidebar label="Main" collapsible><span slot="brand">Kimen</span><ki-sidebar-item href="#home" current> <svg slot="start" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"> <path d="M3 10 12 3l9 7v11H3z" /> </svg> Home</ki-sidebar-item><ki-sidebar-item href="#inbox" count="12"> <svg slot="start" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"> <path d="M4 5h16v14H4zM4 12h4l2 3h4l2-3h4" /> </svg> Inbox</ki-sidebar-item><ki-sidebar-group label="Workspace"> <ki-sidebar-item href="#members">Members</ki-sidebar-item></ki-sidebar-group><ki-button slot="footer" variant="ghost" type="button" aria-label="Account: Ana Garcia">AG</ki-button></ki-sidebar>Use the rail
The toggle keeps focus when the layout changes. Links keep their accessible
names and navigation behavior in the rail, and show their names in tooltips
on hover and keyboard focus. A counted item shows a pill in the panel and a
dot in the rail. Localize its accessible name using count-label.
Set preference.storageKey to a stable key per profile to remember a visitor’s
mode in this browser. The ki-sidebar-change event also reports
detail.collapsed for application-owned persistence. Give each sidebar a
distinct landmark label when several share a page.
Compose account access
The footer slot accepts your account trigger. Connect it to the
application’s menu and give it a name that works at rail width. Keep the
trigger available in both modes. The brand slot is for expanded
presentational branding.
API reference
When to use: navigate more than five top-level destinations or organize application destinations in named groups.
When not to use: for a few destinations, use top navigation. For mobile navigation, use a mobile navigation pattern or a drawer.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
collapse-label | collapseLabel | string | 'Collapse sidebar' | Accessible toggle name while the sidebar is expanded. |
collapsed | collapsed | boolean | false | Display the icon rail. May also be assigned by the application. |
collapsible | collapsible | boolean | false | Show the expand and collapse control. |
expand-label | expandLabel | string | 'Expand sidebar' | Accessible toggle name while the sidebar is collapsed. |
label | label | string | 'Main' | Accessible name for the navigation landmark. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-sidebar-change | CustomEvent<{ collapsed: boolean }> | Reports the new collapsed state after a user toggle. Programmatic writes are silent. |
Slots
| Slot | Description |
|---|---|
| (default) | Navigation routes and groups, in reading order. |
brand | Presentational brand content for the expanded panel. |
footer | Account trigger or other app-owned content available in both modes. |
CSS parts
| Part | Description |
|---|---|
brand | Expanded brand region. |
footer | Region at the foot of the sidebar. |
header | Brand and toggle layout. |
list | List of top-level items and groups. |
nav | Navigation landmark and surface. |
toggle | Native expand and collapse button. |
CSS custom properties
The public styling contract of ki-sidebar: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-density-control-offset | Added to the block size of every scaled control and row (button, icon button, field, select, textarea, option, list item, tab). Components floor the result at ki.size.target-min. |
--ki-density-target-min | The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). |
--ki-focus-ring-color | Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. |
--ki-focus-ring-offset | Gap between a focusable component and its keyboard focus ring. |
--ki-focus-ring-width | Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. |
--ki-sidebar-backdrop-filter | Complete backdrop filter for the panel. |
--ki-sidebar-bg | Navigation panel background. |
--ki-sidebar-bg-image | Optional image over the panel background. |
--ki-sidebar-border | Navigation panel outline. |
--ki-sidebar-border-width | Width of the panel outline. |
--ki-sidebar-brand-weight | Weight of the optional brand label. |
--ki-sidebar-collapsed-width | Compact rail inline size. |
--ki-sidebar-fg | Navigation panel text and brand ink. |
--ki-sidebar-font-family | Typeface of sidebar controls and copy. |
--ki-sidebar-font-size | Font size of navigation labels. |
--ki-sidebar-gap | Space between panel regions and between row contents. |
--ki-sidebar-icon-size | Leading and toggle icon edge. |
--ki-sidebar-item-backdrop-filter | Complete backdrop filter for the row or toggle. |
--ki-sidebar-item-bg | Resting row background. |
--ki-sidebar-item-bg-image | Optional image over navigation row and toggle backgrounds. |
--ki-sidebar-item-fg | Resting row ink, with contrast-more support. |
--ki-sidebar-item-gap | Gap between rows. |
--ki-sidebar-item-height | Base row and toggle height before density adjustment. |
--ki-sidebar-item-hover-bg | Hovered navigation row background. |
--ki-sidebar-item-hover-fg | Hovered navigation row ink. |
--ki-sidebar-item-radius | Corner of a row or toggle. |
--ki-sidebar-line-height | Line height of navigation labels. |
--ki-sidebar-padding | Inset between the panel border and its content. |
--ki-sidebar-radius | Navigation panel corner. |
--ki-sidebar-width | Expanded navigation panel inline size. |
--ki-typography-visually-hidden-size | Nonzero edge for clipped text available to assistive technology. |
When to use: give related sidebar destinations a common heading.
When not to use: as a destination or outside ki-sidebar.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
label | label | string | – | Visible group heading and accessible name of the nested list. |
Slots
| Slot | Description |
|---|---|
| (default) | One or more ki-sidebar-item routes. |
CSS parts
| Part | Description |
|---|---|
heading | Group heading, visually hidden in the rail. |
list | List named by the group heading. |
CSS custom properties
The public styling contract of ki-sidebar-group: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-sidebar-font-family | Typeface of sidebar controls and copy. |
--ki-sidebar-group-backdrop-filter | Complete backdrop filter behind the group heading. |
--ki-sidebar-group-bg | Group heading background. |
--ki-sidebar-group-bg-image | Optional image over the heading background. |
--ki-sidebar-group-fg | Group heading ink, with contrast-more support. |
--ki-sidebar-group-font-family | Group heading typeface. |
--ki-sidebar-group-font-size | Group heading font size. |
--ki-sidebar-group-gap | Space before a group of routes. |
--ki-sidebar-group-line-height | Group heading line height. |
--ki-sidebar-item-gap | Gap between rows. |
--ki-sidebar-item-padding | Inline inset of an expanded row. |
--ki-sidebar-item-weight | Weight of the navigation label. |
When to use: link to a named destination in ki-sidebar or ki-sidebar-group. Register ki-tooltip once when using direct component imports for a rail.
When not to use: for commands, nested controls, or standalone links outside the sidebar.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
count | count | number | undefined | – | Positive unread count. Fractional values round down. |
count-label | countLabel | string | '{label}, {count} new' | Accessible count template, using the {label} and {count} placeholders. |
current | current | boolean | false | Mark this destination as the current page. |
href | href | string | undefined | – | Destination resolved by a native link. Omit for a static row. |
icon-name | iconName | string | undefined | – | Name of a registered Lucide glyph. Import its per-icon entry point first. |
Slots
| Slot | Description |
|---|---|
| (default) | The destination name as text or static inline content. |
start | One decorative icon that overrides icon-name. |
CSS parts
| Part | Description |
|---|---|
count | Expanded pill or rail dot. |
item | Navigation link or static row. |
label | Destination text. |
start | Leading icon holder. |
CSS custom properties
The public styling contract of ki-sidebar-item: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-density-control-offset | Added to the block size of every scaled control and row (button, icon button, field, select, textarea, option, list item, tab). Components floor the result at ki.size.target-min. |
--ki-density-target-min | The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). |
--ki-focus-ring-color | Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. |
--ki-focus-ring-offset | Gap between a focusable component and its keyboard focus ring. |
--ki-focus-ring-width | Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. |
--ki-sidebar-border-width | Width of the panel outline. |
--ki-sidebar-font-family | Typeface of sidebar controls and copy. |
--ki-sidebar-font-size | Font size of navigation labels. |
--ki-sidebar-gap | Space between panel regions and between row contents. |
--ki-sidebar-icon-size | Leading and toggle icon edge. |
--ki-sidebar-item-backdrop-filter | Complete backdrop filter for the row or toggle. |
--ki-sidebar-item-bg | Resting row background. |
--ki-sidebar-item-bg-image | Optional image over navigation row and toggle backgrounds. |
--ki-sidebar-item-count-backdrop-filter | Complete backdrop filter behind the count. |
--ki-sidebar-item-count-bg | Expanded count pill background. |
--ki-sidebar-item-count-bg-image | Optional image over the count background. |
--ki-sidebar-item-count-fg | Expanded count digits. |
--ki-sidebar-item-current-bg | Current destination background. |
--ki-sidebar-item-current-fg | Current destination ink. |
--ki-sidebar-item-dot-bg | Unread dot fill in rail mode. |
--ki-sidebar-item-dot-offset | Inset of the dot from the row block-start and inline-end edges. |
--ki-sidebar-item-dot-ring | Outer ring that separates the rail dot from the row. |
--ki-sidebar-item-fg | Resting row ink, with contrast-more support. |
--ki-sidebar-item-height | Base row and toggle height before density adjustment. |
--ki-sidebar-item-hover-bg | Hovered navigation row background. |
--ki-sidebar-item-hover-fg | Hovered navigation row ink. |
--ki-sidebar-item-padding | Inline inset of an expanded row. |
--ki-sidebar-item-radius | Corner of a row or toggle. |
--ki-sidebar-item-weight | Weight of the navigation label. |
--ki-sidebar-line-height | Line height of navigation labels. |
--ki-typography-visually-hidden-size | Nonzero edge for clipped text available to assistive technology. |