Sidebar

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

# Add this component (its dependencies come along)
npx koalaui-cli@latest add sidebar

Usage#

Anatomy#

Sidebar is a flex column on a bg-card surface. SidebarHeader and SidebarFooter pin to the top and bottom with a hairline separator, and either can hold a SidebarActions cluster beside its switcher; SidebarContent is the scroll region in between. Inside it, SidebarGroup is a navigation section. Give it a SidebarGroupLabel when it needs a heading, or leave it unlabeled for the primary pages. Each SidebarItem is a row; wrap it in a SidebarItemRow when it carries its own actions. The rail and panel, peek, rich row and page tree parts compose around this same skeleton and are listed in the API reference.

import {
  Sidebar,
  SidebarHeader,
  SidebarSwitcher,
  SidebarActions,
  SidebarContent,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarGroupAction,
  SidebarGroupContent,
  SidebarItemRow,
  SidebarItem,
  SidebarItemIcon,
  SidebarItemDot,
  SidebarItemCount,
  SidebarItemActions,
  SidebarItemAction,
  SidebarCollapsible,
  SidebarSeparator,
  SidebarFooter,
} from "@/components/ui/sidebar"

<Sidebar>
  <SidebarHeader>
    <SidebarSwitcher />
    <SidebarActions>...</SidebarActions>
  </SidebarHeader>
  <SidebarContent>
    <SidebarGroup>
      <SidebarGroupLabel />
      <SidebarGroupAction />
      <SidebarGroupContent>
        <SidebarItemRow>
          <SidebarItem>
            <SidebarItemIcon /> {/* or <SidebarItemDot /> */}
            <SidebarItemCount />
          </SidebarItem>
          <SidebarItemActions>
            <SidebarItemAction />
          </SidebarItemActions>
        </SidebarItemRow>
        <SidebarCollapsible>
          <SidebarItem />
        </SidebarCollapsible>
      </SidebarGroupContent>
    </SidebarGroup>
    <SidebarSeparator />
  </SidebarContent>
  <SidebarFooter>
    <SidebarSwitcher />
  </SidebarFooter>
</Sidebar>

Switchers#

SidebarSwitcher is one trigger used for both the workspace switcher (top) and the profile switcher (bottom): a leading visual, a title (with an optional subtitle), and an up/down caret. It renders a real <button>, so it drops straight into a DropdownMenuTrigger asChild. Radix owns the keyboard, focus, and ARIA; the switcher stays lit while its menu is open.

Full switcher#

SidebarSwitcher takes a variant. The default is the compact trigger (a tight gap, a small muted caret, and reduced padding), the everyday switcher, paired with a small leading (an Avatar size="xs", a single initial, or a compact logo tile). Pass variant="full" for the roomier identity row: a wider gap, a heavier title, and room for a subtitle. Pair it with a larger leading (an Avatar size="md", which keeps both initials) for a primary or standalone switcher.

Header actions#

SidebarActions puts icon buttons beside a switcher: search and notifications next to the workspace, the way GitBook and Squarespace head their rail. Drop it into SidebarHeader (or SidebarFooter, for help or settings) after the switcher, and the zone lays the two out as a row: the switcher hugs its name so the caret follows it, and the icons sit at the far edge, in line with the ends of the rows below. Fill it with ghost icon-only Buttons; they take the rail’s muted ink at rest and their aria-label as a tooltip.

This is where an app’s global tools live in the docked shell, which leaves the sheet’s header bar for the page. Collapsed to the icon rail, the buttons stack under the switcher’s mark instead of being cut off.

Items#

A SidebarItem is a <button> by default; pass asChild to wrap an <a> or a Next <Link>. Mark the current page with active (it fills the row and sets aria-current="page"). Lay the children out as <Icon /> Label and push a trailing Badge or count to the right with ml-auto.

Colored icon tiles#

Swap the bare leading glyph for a SidebarItemIcon: a soft, hue-tinted rounded square that gives each destination its own color, the “colored spaces” rail you see in Productboard or Linear. Wrap a single icon and pass a tone (decorative: purple, pink, teal, orange; status: green, blue, red, amber, plus neutral, the default, and brand). The tile scales with density and becomes the centered chip in the collapsed rail. The active row still reads through the neutral chip and ink bar, the tiles decorate, they don’t signal selection.

Nested navigation#

SidebarCollapsible folds a sub-list of routes under a parent row. Give it an icon and label, drop the child SidebarItems inside, and the row gains a caret that toggles them open, built on Radix Collapsible, so it owns the keyboard, focus, and height animation. The sub-list is indented under the label and traced by a guide rail; set active on the parent when one of its child routes is current. In the collapsed icon rail it falls back to a single icon row.

A long sub-list can be split under SidebarGroupLabel sub-headings: inside a sub-list the label stays a plain heading, even when the whole section sits in a collapsible group. With indicator on, folding a branch that holds the current route moves the pill to the first row still on show, so a parent marked active while folded catches it. The docs sidebar on this site is built exactly this way.

Collapsible sections#

Pass collapsible to a SidebarGroup and its SidebarGroupLabel becomes a toggle with a caret. Wrap the rows in SidebarGroupContent so they fold beneath it. Use defaultOpen (or the controlled open/onOpenChange pair) to set the initial state. Unlike nested navigation, this folds a whole flat section rather than revealing sub-routes.

Row states#

Rows carry state, not just selection: unread brings a row to full ink and semibold, muted sinks it, and SidebarItemCount adds a quiet tabular count. Wrap a row in SidebarItemRow to give it hover-revealed SidebarItemActions, and add a SidebarGroupAction after a heading for a section +. In the collapsed rail unread becomes a small ink dot on the glyph, and counts and actions step aside.

A plain count takes the row’s own ink, so a column of totals reads as one quiet figure per row and lifts only where the row is active or unread. Reach for a Badge when the number is a label rather than a count. For a colour where the icon goes (a mail label, a project), use SidebarItemDot: it fills the same 20px glyph column, so dotted and iconed rows line up (the Mail recipe below uses it for labels).

Collapsed (icon rail)#

The rail has two variants, driven by the same markup. The default is the full-width rail; collapsed shrinks it to a 48px icon-only column. Labels go sr-only, each row becomes a centered icon, the active row is marked with a left ink bar instead of a full chip, sections are divided by a short rule, and the switcher reduces to its leading visual. Give every SidebarItem a label so the collapsed row gets a hover tooltip and an accessible name, and mark secondary sections with <SidebarGroup hideWhenCollapsed> so they drop out of the rail rather than reducing to bare glyphs.

Stacked (labeled icon rail)#

layout="stacked" is the rail Slack and Teams lead with: a 72px column where every row sets its glyph in a rounded tile and keeps a short label underneath. The tile is the whole marker, lit on hover and held while active, and a Badge in the row pins to its corner as the unread count. Like the collapsed rail, headings go sr-only, sections split on a short rule and the switchers reduce to their mark. Set it beside an ordinary rail for the two-pane workspace shell: the stacked rail picks the area, the list rail carries its channels.

Bare stacked#

The stacked rail lights a rounded tile behind the glyph on hover and selection, the Slack read. Pass tile={false} for the bare rail of Teams: no tile at all, the current row carries the ink edge bar and its glyph and label turn full ink. The glyph keeps its padded box either way, so badges and unread dots pin to the same corner.

Rail and panel#

SidebarPanels pairs a narrow icon rail with a 240px panel for the area it selects, as in Supabase, Discord or the VS Code activity bar. The rail is a keyboard-navigable tablist, and each SidebarPanel is an ordinary list Sidebar with its own title and groups. Clicking the open area again folds the panel away (collapseOnReselect); turn that off for a console where the panel is always out.

With collapseOnReselect on (the default) the rail behaves like the VS Code activity bar: click the open view and the panel folds, leaving no lit row and the whole width to the content. Opening and closing animate the panel’s width; switching areas while open is an instant swap. Drive it from anywhere inside with useSidebarPanels().

Peek#

SidebarPeek shows a rail on demand. mode="expand" keeps a 48px icon rail that widens over the page after a short hover or keyboard focus, so the content never moves. Pin it with SidebarPeekPin to dock it; the peek closes on leave, Escape or focus out, and holds while a menu inside it is open.

Two trade-offs are deliberate. While it peeks, the rail keeps its icon-rail form, so headings stay short rules and hideWhenCollapsed groups and nested sub-lists only appear once it is pinned. And pinning reflows the page on purpose: it is the one change that should move the content, so the column tweens to the full width.

mode="offcanvas" hides the rail entirely and slides it in as a floating card from an 8px hot zone on the left edge or from a SidebarPeekTrigger in the content. Resting on the trigger peeks; clicking it docks the rail, and clicking again sends it away. SidebarPeek renders no DOM, so the trigger can live in any top bar.

Rich rows#

SidebarRichItem is the same SidebarItem one size up, for rails whose rows are records: leading media, a title with a timestamp, a one-line preview and an unread count. Collapsed, only the avatars or covers remain, with a dot marking unread. The text block is a fixed two-by-two grid, so any part can be left out.

size="lg" is the library row: a 48px cover, square or round by shape, with a SidebarItemMeta placement="center" for a now-playing glyph. SidebarHeaderRow, SidebarTitle and SidebarFilters stack a titled header, a scrolling chip row and a search row in one SidebarHeader.

Page tree#

SidebarTree nests pages to any depth with a 12px step per level. On hover or focus a page’s icon turns into its caret, and its actions (a … menu, a +) appear at the row’s end. Rows match SidebarItem exactly, the keyboard model is the one Tree uses, and clicking a row navigates while only the caret folds.

In the collapsed rail the tree shrinks to its top-level pages: each one a glyph with its label as a tooltip, lit while the open page sits anywhere beneath it. A section whose pages mean nothing as bare glyphs should pass hideWhenCollapsed to its SidebarGroup instead, as Favorites does here.

Docked (in an app shell)#

A rail standing on its own is a card: it paints bg-card and a hairline against the content beside it. Inside an app shell it shouldn’t: the shell already owns the surface, and a second fill on top of it is the difference between a docked dashboard and a rail bolted onto one. So nesting a Sidebar in a LayoutSidebar turns docked on for you: no fill, no hairline, and the width comes from the shell column, which is also what animates the collapse.

The same applies in LayoutMobileSidebar, where the drawer panel is the surface. Pass docked explicitly to force the treatment outside a Layout, or docked={false} to opt a rail out of the shell it sits in. Combined with floating below, the card treatment wins: that pair is the detached rail floating in the shell gutter.

Floating (inset)#

floating detaches the rail into an inset card: a full outline, a rounded radius concentric with the app shell, and a shadow that lifts it off the canvas, instead of a single edge hairline. Pair it with padding on the container (or the Layout gutter) so it floats clear of the viewport edges.

Right side#

side="right" docks the rail against the right edge. The separating hairline flips to its left so it reads as an inspector/detail panel beside the main content. Everything else (switchers, sections, density) is symmetric.

Density#

density on Sidebar flows through context to the zone padding, the inter-section gap, the row height, and the switcher padding. compact is the default (app UI); comfortable is roomier. Set it once here or for a whole subtree with DensityProvider. See Density.

Recipes#

Five finished rails built from the parts above, nothing bespoke: each one is plain composition of rows, states, counts and the footer. Lift one whole into an app, or use it as the reference for how the parts combine.

Teams, as in Linear: each team folds its own views under a tinted tile.

Mail: one Compose action, folders with a column of totals, labels as colour dots.

Usage quota: the plan’s meter and its upgrade sit at the foot, above the profile.

Presence: direct messages lead with an avatar carrying its status dot.

User card, as in Discord: the profile, then mute, deafen and settings at one size.

API reference#

FAQ#