Sidebar

An application sidebar: a collapsible navigation column, with a phone form and a desktop form.

Live Examples

Sub-items and a loading state

Import

import {
  SidebarProvider,
  Sidebar,
  SidebarHeader,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarMenu,
  SidebarMenuItem,
  SidebarMenuButton,
  SidebarInset,
  SidebarTrigger,
} from "@jarllyng/nostromo";

Parts

Props

SidebarProvider

Sidebar

SidebarMenuButton

The phone form is a different tree

Below 768px a Sidebar is a Sheet: a modal panel over the page. Above it, a fixed column beside the page. Those are different elements with different semantics, so the branch happens in JS rather than in CSS.

Two things follow from that.

Put SidebarTrigger in the inset, not in the sidebar. On a phone the sidebar is a closed dialog, and everything inside it is unrendered - a trigger in there could never be reached to open it.

The open state is two states. open is the desktop column, openMobile is the sheet. toggleSidebar picks whichever applies, and useSidebar exposes both.

State goes in a cookie, and your server has to read it

Collapsing the sidebar writes sidebar_state. That is what stops it flashing open on every navigation in a server-rendered app - but only if the server passes it back as defaultOpen. Nothing in the component can do that for you.

In a Next.js layout:

import { cookies } from "next/headers";
 
export default async function Layout({ children }) {
  const store = await cookies();
  const defaultOpen = store.get("sidebar_state")?.value !== "false";
 
  return (
    <SidebarProvider defaultOpen={defaultOpen}>{children}</SidebarProvider>
  );
}

Left alone, the cookie is written and never read, and the sidebar starts expanded every time.

Colours are their own token family

bg-sidebar, text-sidebar-foreground, border-sidebar-border, bg-sidebar-accent, text-sidebar-accent-foreground and ring-sidebar-ring, so a sidebar can be a different surface from a card.

Every theme defaults them to that theme’s own card, accent, border and ring, so nothing looks different until you override them:

[data-theme="nostromo"] {
  --nostromo-color-sidebar: 240 6% 10%;
  --nostromo-color-sidebar-foreground: 0 0% 98%;
  --nostromo-color-sidebar-border: 240 4% 20%;
}

Values are HSL channels without the hsl(), same as every other token.

Keyboard

⌘B on a Mac, Ctrl+B elsewhere, toggles the sidebar. Pass keyboardShortcut={false} if the key is already taken in your app.

SidebarTrigger carries aria-expanded, so a screen reader user knows whether pressing it opens or closes. SidebarRail does the same thing with a pointer and is deliberately outside the tab order: two tab stops for one action is worse than one.