Skip to content
Kimenpre-v1documentation home
Color scheme

ki-sidebar

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.

Theme for this example
Color scheme for this example
Kimen Home Inbox Members AG
<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

AttributePropertyTypeDefaultDescription
collapse-labelcollapseLabelstring'Collapse sidebar'Accessible toggle name while the sidebar is expanded.
collapsedcollapsedbooleanfalseDisplay the icon rail. May also be assigned by the application.
collapsiblecollapsiblebooleanfalseShow the expand and collapse control.
expand-labelexpandLabelstring'Expand sidebar'Accessible toggle name while the sidebar is collapsed.
labellabelstring'Main'Accessible name for the navigation landmark.

Events

EventDetail typeDescription
ki-sidebar-changeCustomEvent<{ collapsed: boolean }>Reports the new collapsed state after a user toggle. Programmatic writes are silent.

Slots

SlotDescription
(default)Navigation routes and groups, in reading order.
brandPresentational brand content for the expanded panel.
footerAccount trigger or other app-owned content available in both modes.

CSS parts

PartDescription
brandExpanded brand region.
footerRegion at the foot of the sidebar.
headerBrand and toggle layout.
listList of top-level items and groups.
navNavigation landmark and surface.
toggleNative 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.

TokenDescription
--ki-density-control-offsetAdded 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-minThe 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-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-offsetGap between a focusable component and its keyboard focus ring.
--ki-focus-ring-widthThickness 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-filterComplete backdrop filter for the panel.
--ki-sidebar-bgNavigation panel background.
--ki-sidebar-bg-imageOptional image over the panel background.
--ki-sidebar-borderNavigation panel outline.
--ki-sidebar-border-widthWidth of the panel outline.
--ki-sidebar-brand-weightWeight of the optional brand label.
--ki-sidebar-collapsed-widthCompact rail inline size.
--ki-sidebar-fgNavigation panel text and brand ink.
--ki-sidebar-font-familyTypeface of sidebar controls and copy.
--ki-sidebar-font-sizeFont size of navigation labels.
--ki-sidebar-gapSpace between panel regions and between row contents.
--ki-sidebar-icon-sizeLeading and toggle icon edge.
--ki-sidebar-item-backdrop-filterComplete backdrop filter for the row or toggle.
--ki-sidebar-item-bgResting row background.
--ki-sidebar-item-bg-imageOptional image over navigation row and toggle backgrounds.
--ki-sidebar-item-fgResting row ink, with contrast-more support.
--ki-sidebar-item-gapGap between rows.
--ki-sidebar-item-heightBase row and toggle height before density adjustment.
--ki-sidebar-item-hover-bgHovered navigation row background.
--ki-sidebar-item-hover-fgHovered navigation row ink.
--ki-sidebar-item-radiusCorner of a row or toggle.
--ki-sidebar-line-heightLine height of navigation labels.
--ki-sidebar-paddingInset between the panel border and its content.
--ki-sidebar-radiusNavigation panel corner.
--ki-sidebar-widthExpanded navigation panel inline size.
--ki-typography-visually-hidden-sizeNonzero 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

AttributePropertyTypeDefaultDescription
labellabelstring–Visible group heading and accessible name of the nested list.

Slots

SlotDescription
(default)One or more ki-sidebar-item routes.

CSS parts

PartDescription
headingGroup heading, visually hidden in the rail.
listList 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.

TokenDescription
--ki-sidebar-font-familyTypeface of sidebar controls and copy.
--ki-sidebar-group-backdrop-filterComplete backdrop filter behind the group heading.
--ki-sidebar-group-bgGroup heading background.
--ki-sidebar-group-bg-imageOptional image over the heading background.
--ki-sidebar-group-fgGroup heading ink, with contrast-more support.
--ki-sidebar-group-font-familyGroup heading typeface.
--ki-sidebar-group-font-sizeGroup heading font size.
--ki-sidebar-group-gapSpace before a group of routes.
--ki-sidebar-group-line-heightGroup heading line height.
--ki-sidebar-item-gapGap between rows.
--ki-sidebar-item-paddingInline inset of an expanded row.
--ki-sidebar-item-weightWeight 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

AttributePropertyTypeDefaultDescription
countcountnumber | undefined–Positive unread count. Fractional values round down.
count-labelcountLabelstring'{label}, {count} new'Accessible count template, using the {label} and {count} placeholders.
currentcurrentbooleanfalseMark this destination as the current page.
hrefhrefstring | undefined–Destination resolved by a native link. Omit for a static row.
icon-nameiconNamestring | undefined–Name of a registered Lucide glyph. Import its per-icon entry point first.

Slots

SlotDescription
(default)The destination name as text or static inline content.
startOne decorative icon that overrides icon-name.

CSS parts

PartDescription
countExpanded pill or rail dot.
itemNavigation link or static row.
labelDestination text.
startLeading 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.

TokenDescription
--ki-density-control-offsetAdded 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-minThe 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-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-offsetGap between a focusable component and its keyboard focus ring.
--ki-focus-ring-widthThickness 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-widthWidth of the panel outline.
--ki-sidebar-font-familyTypeface of sidebar controls and copy.
--ki-sidebar-font-sizeFont size of navigation labels.
--ki-sidebar-gapSpace between panel regions and between row contents.
--ki-sidebar-icon-sizeLeading and toggle icon edge.
--ki-sidebar-item-backdrop-filterComplete backdrop filter for the row or toggle.
--ki-sidebar-item-bgResting row background.
--ki-sidebar-item-bg-imageOptional image over navigation row and toggle backgrounds.
--ki-sidebar-item-count-backdrop-filterComplete backdrop filter behind the count.
--ki-sidebar-item-count-bgExpanded count pill background.
--ki-sidebar-item-count-bg-imageOptional image over the count background.
--ki-sidebar-item-count-fgExpanded count digits.
--ki-sidebar-item-current-bgCurrent destination background.
--ki-sidebar-item-current-fgCurrent destination ink.
--ki-sidebar-item-dot-bgUnread dot fill in rail mode.
--ki-sidebar-item-dot-offsetInset of the dot from the row block-start and inline-end edges.
--ki-sidebar-item-dot-ringOuter ring that separates the rail dot from the row.
--ki-sidebar-item-fgResting row ink, with contrast-more support.
--ki-sidebar-item-heightBase row and toggle height before density adjustment.
--ki-sidebar-item-hover-bgHovered navigation row background.
--ki-sidebar-item-hover-fgHovered navigation row ink.
--ki-sidebar-item-paddingInline inset of an expanded row.
--ki-sidebar-item-radiusCorner of a row or toggle.
--ki-sidebar-item-weightWeight of the navigation label.
--ki-sidebar-line-heightLine height of navigation labels.
--ki-typography-visually-hidden-sizeNonzero edge for clipped text available to assistive technology.

Open Sidebar in Storybook