Sidebar
kumo-svelte

Sidebar

A composable sidebar navigation component with contained layouts, peeking, sliding views, resizing, icon-only mode, and responsive mobile support.

Main content area
<script lang="ts">
  import { Sidebar } from 'kumo-svelte';
  import { Globe, House } from 'phosphor-svelte';
</script>

<Sidebar.Provider defaultOpen>
  <Sidebar>
    <Sidebar.Content>
      <Sidebar.Group>
        <Sidebar.GroupLabel>Overview</Sidebar.GroupLabel>
        <Sidebar.Menu>
          <Sidebar.MenuButton icon={House} active>Home</Sidebar.MenuButton>
          <Sidebar.MenuButton icon={Globe}>Domains</Sidebar.MenuButton>
        </Sidebar.Menu>
      </Sidebar.Group>
    </Sidebar.Content>
  </Sidebar>
</Sidebar.Provider>

Installation

Barrel

import { Sidebar } from "kumo-svelte";

Granular

import { Sidebar } from "kumo-svelte/components/sidebar";

Usage

At minimum you need Provider, Sidebar, Content (scrollable area), Menu, and MenuButton. Add Header / Footer to pin content above or below the scroll area. Use Group + GroupLabel to organize sections.

<script lang="ts">
  import { Sidebar } from 'kumo-svelte';
  import { Code, Gear, House } from 'phosphor-svelte';
</script>

<Sidebar.Provider defaultOpen>
  <Sidebar>
    <Sidebar.Content>
      <Sidebar.Group>
        <Sidebar.GroupLabel>Navigation</Sidebar.GroupLabel>
        <Sidebar.Menu>
          <Sidebar.MenuButton icon={House} active>Home</Sidebar.MenuButton>
          <Sidebar.MenuItem>
            <Sidebar.Collapsible>
              <Sidebar.CollapsibleTrigger>
                <Sidebar.MenuButton icon={Code}>
                  Compute <Sidebar.MenuChevron />
                </Sidebar.MenuButton>
              </Sidebar.CollapsibleTrigger>
              <Sidebar.CollapsibleContent>
                <Sidebar.MenuSub>
                  <Sidebar.MenuSubButton>Workers</Sidebar.MenuSubButton>
                </Sidebar.MenuSub>
              </Sidebar.CollapsibleContent>
            </Sidebar.Collapsible>
          </Sidebar.MenuItem>
        </Sidebar.Menu>
      </Sidebar.Group>
    </Sidebar.Content>
    <Sidebar.Footer>
      <Sidebar.MenuButton icon={Gear}>Settings</Sidebar.MenuButton>
    </Sidebar.Footer>
  </Sidebar>
  <main class="flex-1">
    <!-- page content -->
  </main>
</Sidebar.Provider>

Examples

Basic

The minimum viable sidebar: just groups, menu buttons, and collapsible sub-menus. No header or footer. MenuButton and MenuSubButton auto-wrap in <li> — no MenuItem / MenuSubItem needed.

Main content area
<Sidebar.Provider defaultOpen>
  <Sidebar>
    <Sidebar.Content>
      <Sidebar.Group>
        <Sidebar.GroupLabel>Overview</Sidebar.GroupLabel>
        <Sidebar.Menu>
          <Sidebar.MenuButton icon={House} active>Home</Sidebar.MenuButton>
          <Sidebar.MenuButton icon={ChartBar}>Analytics</Sidebar.MenuButton>
        </Sidebar.Menu>
      </Sidebar.Group>
    </Sidebar.Content>
  </Sidebar>
</Sidebar.Provider>

Toggle & Collapsed State

Use Sidebar.Trigger in the footer or useSidebar().toggleSidebar programmatically. Pass tooltip to show labels on hover when collapsed.

Click the button or the sidebar trigger to toggle

<Sidebar.MenuButton icon={House} tooltip="Home" active>
  Home
</Sidebar.MenuButton>

<Sidebar.Footer>
  <Sidebar.Trigger />
</Sidebar.Footer>

Resizable

Drag the edge to resize. Dragging below minWidth collapses; dragging outward from collapsed expands.

Drag the sidebar edge to resize

<Sidebar.Provider defaultOpen resizable defaultWidth={240} minWidth={180} maxWidth={400}>
  <Sidebar>
    <Sidebar.Content>...</Sidebar.Content>
    <Sidebar.ResizeHandle />
  </Sidebar>
</Sidebar.Provider>

Right Side

Use side="right" for a sidebar on the right edge. Place <main> before <Sidebar> in the DOM.

Main content area
<Sidebar.Provider defaultOpen side="right">
  <main class="flex-1">...</main>
  <Sidebar>
    <Sidebar.Content>
      <Sidebar.Group>
        <Sidebar.GroupLabel>Details</Sidebar.GroupLabel>
        <Sidebar.Menu>
          <Sidebar.MenuButton icon={Gear} active>Properties</Sidebar.MenuButton>
          <Sidebar.MenuButton icon={ChartBar}>Metrics</Sidebar.MenuButton>
        </Sidebar.Menu>
      </Sidebar.Group>
    </Sidebar.Content>
  </Sidebar>
</Sidebar.Provider>

Peeking

Set peekable on the provider so a collapsed icon sidebar can temporarily reveal its full width on hover or focus.

State: Expanded

Collapse, then hover the sidebar to peek

<Sidebar.Provider defaultOpen={false} peekable contained>
  <Sidebar>
    <Sidebar.Content>
      <Sidebar.MenuButton icon={House} active>Home</Sidebar.MenuButton>
    </Sidebar.Content>
  </Sidebar>
</Sidebar.Provider>

Auto Scroll

Use autoScrollOnOpen on long collapsible sections to keep newly revealed content in view.

Open Workers near the bottom of the list

<Sidebar.Collapsible autoScrollOnOpen>
  <Sidebar.CollapsibleTrigger>
    <Sidebar.MenuButton icon={Code}>
      Workers <Sidebar.MenuChevron />
    </Sidebar.MenuButton>
  </Sidebar.CollapsibleTrigger>
  <Sidebar.CollapsibleContent>
    <Sidebar.MenuSub>...</Sidebar.MenuSub>
  </Sidebar.CollapsibleContent>
</Sidebar.Collapsible>

Sliding Views

Use SlidingViews and SlidingView to switch between nested sidebar panels without replacing the provider.

Active: Account surface

Click the header button to slide between views

<Sidebar.Provider contained>
  <Sidebar>
    <Sidebar.SlidingViews activeKey={view}>
      <Sidebar.SlidingView value="overview">...</Sidebar.SlidingView>
      <Sidebar.SlidingView value="settings">...</Sidebar.SlidingView>
    </Sidebar.SlidingViews>
  </Sidebar>
</Sidebar.Provider>

Full Example

Kitchen sink: header with account switcher, search input, badges, collapsible sub-menus, and a footer action.

Main content area
<Sidebar>
  <Sidebar.Header>
    <AccountSwitcher />
  </Sidebar.Header>
  <Sidebar.Content>
    <Sidebar.Group>
      <Sidebar.Menu>
        <Sidebar.MenuButton icon={Lock}>
          Zero Trust
          <Sidebar.MenuBadge>Beta</Sidebar.MenuBadge>
        </Sidebar.MenuButton>
      </Sidebar.Menu>
    </Sidebar.Group>
  </Sidebar.Content>
  <Sidebar.Footer>
    <Sidebar.MenuButton icon={Gear}>Manage account</Sidebar.MenuButton>
  </Sidebar.Footer>
</Sidebar>

Mobile

On narrow viewports the sidebar renders as a navigation drawer. Use mobileBreakpoint to control the threshold.

Click the button to open the mobile sidebar

Press Escape or click the backdrop to close

<Sidebar.Provider mobileBreakpoint={9999}>
  <Sidebar>
    <Sidebar.Content>...</Sidebar.Content>
  </Sidebar>
</Sidebar.Provider>

API Reference

The main sidebar container. Renders as <aside> on desktop and a navigation drawer on mobile.

PropTypeDefaultDescription
variant "sidebar" | "floating" | "inset""sidebar"Sidebar layout variant inherited from Provider.
side "left" | "right""left"Side of the viewport or layout where the sidebar renders.
collapsible "icon" | "offcanvas" | "none""icon"Collapse behavior inherited from Provider.
children *Snippet-Sidebar content — Header, Content, Footer, groups, menus, and related slots.
contentClass string-Additional classes for the desktop content container.
class string-Additional classes for the sidebar element.

Context provider managing expand/collapse state and mobile detection.

PropTypeDefaultDescription
defaultOpen booleantrueInitial open state when uncontrolled.
open boolean-Controlled open state.
onOpenChange (open: boolean) => void-Callback when open state changes.
variant "sidebar" | "floating" | "inset""sidebar"Sidebar layout variant.
side "left" | "right""left"Which side the sidebar is on.
collapsible "icon" | "offcanvas" | "none""icon"Collapse behavior for the sidebar.
resizable booleanfalseEnable drag-to-resize on the sidebar edge.
defaultWidth number256Initial width in pixels when resizable.
minWidth number200Minimum width in pixels when resizing.
maxWidth number480Maximum width in pixels when resizing.
onWidthChange (width: number) => void-Callback when width changes during resize.
contained booleanfalseKeeps the provider scoped to its parent container instead of using full viewport height.
peekable booleanfalseAllows collapsed sidebars to temporarily reveal full content while hovered or focused.
animationDuration number250Transition duration in milliseconds for width and peek animations.
mobileBreakpoint number768Viewport width below which the sidebar renders as a mobile navigation drawer.

Sidebar.Content

Scrollable middle section (flex-1 overflow-y-auto). Use Header / Footer to pin content above or below this scroll area.

Primary interactive element. Supports icons, active state, links, and auto-tooltip when collapsed.

PropTypeDefaultDescription
icon Component | Snippet-Icon rendered before the label.
active booleanfalseMarks this item as currently active.
size "base" | "sm""base"Button size.
href string-Navigation URL. When set, renders as a link.
tooltip string-Tooltip label shown when the sidebar is collapsed.

Button inside a sub-menu for nested navigation.

PropTypeDefaultDescription
active booleanfalseMarks this sub-item as currently active.
href string-Navigation URL. When set, renders as a link.

Button that toggles provider open state.

Keyboard and pointer resize control for resizable sidebars.

Container for keyed sliding sidebar panels.

Panel rendered when its value matches the parent activeKey.