Sidebar
The app's navigation and top bar in one component: a column that collapses to an icon rail and becomes a sticky strip on a narrow screen.
Installation
npx shadcn@latest add @flyingsalmon/sidebarUsage
import { CalendarDays, PanelLeft, Wallet } from 'lucide-react'
import {
Sidebar,
SidebarContent,
SidebarHeader,
SidebarItem,
SidebarNav,
SidebarProvider,
SidebarTrigger,
} from '@/components/ui/sidebar'
export function SidebarUsage() {
return (
<SidebarProvider className="h-screen">
<Sidebar>
<SidebarHeader>
<SidebarTrigger>
<PanelLeft />
</SidebarTrigger>
</SidebarHeader>
<SidebarContent>
<SidebarNav aria-label="Trip">
<SidebarItem icon={<CalendarDays />} aria-current="page">
Itinerary
</SidebarItem>
<SidebarItem icon={<Wallet />}>Wallet</SidebarItem>
</SidebarNav>
</SidebarContent>
</Sidebar>
<main className="flex-1 p-6">The page</main>
</SidebarProvider>
)
}Examples
Groups
A group label names a cluster of items. In the rail the label becomes a rule, so the groups still read as groups and the items below never jump. Collapse the sidebar to see it.
Nested items
A parent is a page like any other, and its chevron opens the list of children. Close the list while Alfama is current and the bar springs up to Days.
Starting collapsed
defaultCollapsed opens the sidebar as a rail. Each icon shows its label in a tooltip on hover and on focus.
Guidelines
When to use
- For the primary navigation of the app: a trip’s itinerary, places, budget, and travellers.
- As the app’s top bar. On a narrow screen the sidebar becomes the bar, so there is no separate header component to build.
When not to use
- Use Breadcrumb to climb back up through a hierarchy within one section, because a sidebar moves between sections.
- Use Tabs to switch between peer panels on one page, because those are views of the same content rather than places.
- Use Drawer for filters or detail that accompanies the page, because the sidebar is for navigation only.
Do and don’t
- DoKeep the sidebar on screen across every page, so the current-page bar slides from item to item as the traveller moves.The moving bar shows where the traveller went from where they were. A sidebar that redraws on each page draws the bar in place, and the app reads as separate pages.
- DoGive every item an icon.The rail shows icons alone, so an item without one has nothing to show there.
- DoIn the rail, drop names from the header and the footer and keep their icons.The rail is one icon wide, so a name either clips or forces the column wider. Expanding the sidebar brings the names back.
- DoKeep the top level to a handful of sections, and nest the traveller’s own things, such as their trips or days, under the section they belong to.A short top level reads at a glance and fits the rail. A nest grows with the traveller’s content without pushing the sections apart.
- Don’tMake the traveller’s account a navigation item.The nav lists places in the app; the account is the person using it. It goes in the footer as one item that opens a menu, in reach from every page.
- Don’tList a place the traveller can no longer use, such as a trip that has ended.Leave it out rather than greying it. A dimmed item is a stop the traveller reads and cannot take.
Accessibility
| Key | Description |
|---|---|
| TabShift+Tab | Moves through the trigger, the items, and the footer controls. A nest parent is one stop and its chevron toggle is the next. |
| EnterSpace | Activates the focused item, toggles a nest, or collapses and expands the sidebar from the trigger. |
| Escape | In the strip, closes the navigation menu and returns focus to the trigger. |
There are no arrow keys: these are links in a landmark, not a menu. SidebarNav is a nav and requires an aria-label. The trigger carries aria-expanded and aria-controls pointed at the aside, and is named “Collapse sidebar” or “Expand sidebar”. In the strip it is named “Open navigation”, carries aria-haspopup="dialog", and its aria-expanded follows the menu, a modal dialog titled “Navigation” that traps focus and hands it back to the trigger when it closes.
A rail item’s accessible name never depends on its tooltip: the label stays in the DOM, clipped rather than removed, so a screen reader reads the same nav in either layout. A nest toggle carries aria-expanded and aria-controls pointed at its list. A focused item takes the same --accent background as one under the pointer and draws no ring, so the pointer and the keyboard land on the same mark; the current page keeps its own, the bar and the --foreground label, so the two stay distinguishable.
API
SidebarProvider
Holds the collapsed state and the layout. Also takes every <div> attribute; size the sidebar and the pane through className. Put it in a persistent layout route so it stays mounted across navigation; one that remounts draws the current-page bar in place instead of sliding it.
| Prop | Type | Default | Description |
|---|---|---|---|
| collapsed | boolean | – | Controls the collapsed state. |
| defaultCollapsed | boolean | false | The initial collapsed state when uncontrolled. |
| onCollapsedChange | (collapsed: boolean) => void | – | Called when the trigger collapses or expands. |
SidebarItem
A navigation item. Also takes every <button> attribute.
| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | – | The label, or with asChild the one element that wraps it. Pass the label as a plain string: the rail shows it as a tooltip. A label made of markup stays visible in the rail instead. |
| icon | ReactNode | – | The icon before the label. |
| asChild | boolean | false | Renders its single child, such as your router’s link, with the item styling and the label slotted into it. |
| aria-current | "page" | undefined | – | Marks the current page and draws the bar. The item reads it from itself or from the element asChild renders, so a router link that sets it needs nothing else. Nothing else marks the current page. |
SidebarNest
Wraps a parent SidebarItem and a SidebarNestItems list.
| Prop | Type | Default | Description |
|---|---|---|---|
| open | boolean | – | Controls whether the list is open. |
| defaultOpen | boolean | false | The initial state when uncontrolled. |
| onOpenChange | (open: boolean) => void | – | Called when the toggle opens or closes the list. |
SidebarNav
| Prop | Type | Default | Description |
|---|---|---|---|
| aria-label | string | Required | Names the nav landmark. |
SidebarTrigger
An outline icon button that collapses and expands the sidebar, or opens the menu in the strip. Also takes every Button prop except variant, size, loading, and icon.
| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | Required | The glyph. The registry ships no icons, so you pass yours. |
useSidebar() returns collapsed, setCollapsed, and layout, which is a SidebarLayout: Expanded, Collapsed, or Strip. The header and footer are your slots, so branch on layout to drop content too wide for the rail, as the demo does with the trip name. The remaining parts (Sidebar, SidebarHeader, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupLabel, SidebarNestItems) take only their element’s props.