Sidebar

When to use

Use Sidebar for a collapsible application sidebar whose contents you assemble yourself: a workspace switcher, a search field, a project list, per-row secondary menus, a user card in the footer.

How to choose among the three neighbours:

They do not compete. Sidebar owns the shell only, so anything can live inside it, including a <NavMenu> placed in <SidebarContent> when you do want a data-driven menu. AdminLayout is the pre-wired product built from shell plus NavMenu plus header plus tabs; its shape is fixed and cannot host the custom parts listed above, so drop down to Sidebar when you need them.

Import

Props

SidebarProvider

The state machine and the layout root. It renders a horizontal flex container whose two direct children are Sidebar and SidebarInset.

#### Warning: mobileBreakpoint differs by 1px from the LayoutSider and AdminLayout breakpoint

The same breakpoint name "md" carries two coexisting meanings in this library, and their boundaries are exactly one pixel apart:

Both are deliberate, but they answer different questions. The first reads the breakpoint value as the collapse threshold itself; that is its established meaning and a test pins it down. The second matches Tailwind's `md:` = `min-width: 768px`, so that "the page starts laying out as desktop" and "Sidebar starts rendering as desktop" happen at the same instant. Aligning it with the first would tear exactly at 768px: the page would already be in its desktop layout while the sidebar was still a drawer. An iPad in portrait is exactly 768px wide, so this is not a theoretical edge.

Keep the one-pixel gap in mind when you use both components together. If you need them to line up exactly, pass numbers on both sides (breakpoint={768} equals mobileBreakpoint={769}, or the other way round) instead of assuming the shared name means the same thing.

Sidebar

SidebarMenuButton

Remaining structural parts

Events

Slots

useSidebar()

Call it from any descendant of SidebarProvider. It throws outside the provider instead of falling back silently.

Three collapse modes

Example

Pitfalls

• Secondary actions must be siblings. Put SidebarMenuAction and SidebarMenuBadge inside SidebarMenuItem next to SidebarMenuButton; they cover the right edge through absolute positioning. Nesting them inside the button produces button > button, which React reports during hydration and which hides the second control from screen readers.
• Wrap labels in a `<span>` for icon mode. Collapsing works through [&>span:last-child]:hidden. A bare text child such as <Folder /> Projects has no node to hide, so the text is clipped into a fragment instead.
• Nothing inside an `offcanvas` sidebar is reachable once collapsed, including SidebarRail. Keep another SidebarTrigger in the content area or the user can never reopen it.
• Persistence is not built in. open and onOpenChange are exposed so you can wire a cookie, localStorage, or a server-side preference. A cookie hardcoded in the library would fight SSR first paint, multi-tenant setups, and privacy policies.
• Never randomize `SidebarMenuSkeleton.width`. A random width is rolled once on the server and again on the client, which guarantees a hydration mismatch. Pass a deterministic list such as ["78%", "62%", "88%"] if you want uneven bars.
• `isMobile` is `false` during SSR and on the first frame. It comes from matchMedia inside an effect, so the first tree is always the desktop shape; that is what keeps SSR and hydration identical. If a narrow viewport must render the drawer on first paint, detect it from the user agent on the server and drive the state yourself.
• Change `tooltipSide` for a right-hand sidebar. With side="right" the tooltip still points right by default and flies off screen; pass tooltipSide="left".

Depth: sidebar surface and inset

By default the sidebar shares --color-surface with Card and Popover. If your bridge layer maps `surface` and `bg` to the same color (both pure white is the common light-mode case), the sidebar, the page background and the content area all end up the same color with only a 1px border between them, whereas a shadcn-lineage application sidebar usually carries one step of contrast there: the navigation plane sits behind, the content sits in front (#224).

Two independent escape hatches; use either or both:

• --hl-sidebar-surface falls back to `--color-surface`, so leaving it unset changes nothing. It only covers the sidebar (including the copy inside the mobile drawer) and touches no other component, which is exactly why editing --color-surface is the wrong lever: that one is the shared surface color of the whole library.
• variant="inset" requires SidebarInset to be the next sibling of Sidebar (same level, no div in between): the island styling reads the preceding sibling through peer-data-*. That is the same structural requirement as "Why in-flow rather than fixed" below, so correct markup already satisfies it.
• On mobile the sidebar becomes a drawer and leaves the flow, so inset does not apply there (same as shadcn).
• Under inset the sidebar draws no divider (the gutter already separates them), and with collapsible="offcanvas" that 8px gutter collapses to zero as well. Otherwise a width: 0 sidebar would still occupy 16px of padding and look like it never closed. That is also why this step cannot be reproduced with className="p-2" at the call site: collapsing would always leave a strip behind.

Reduced motion is the library's job

Opening and closing the sidebar is a page-level container transform, so under prefers-reduced-motion: reduce the component drops the width transition by itself (#225). Consumers need to do nothing.

The width transition lives in an inline style (duration and easing come from the motion tokens; utility classes are avoided so that projects importing only preset-core.css still get the same curve), and an inline style outranks every ordinary CSS rule: overriding it takes !important plus a selector that guesses the library's internal DOM structure, which fails silently the moment that structure changes, and what fails is an accessibility preference with no error to show for it. So the component owns it: if any component still moves under reduced motion, file it as a bug rather than stacking !important on the consumer side.

When your own hand-rolled motion needs the same signal, use the exported hook instead of writing another matchMedia:

Why the shortcut yields

The built-in shortcut is Cmd/Ctrl + B. It never fires in four situations: event.defaultPrevented (someone already handled the key), inside input / textarea / select, on a contenteditable element, and inside a descendant of a `contenteditable` element.

The last one is the easy miss: when the caret sits on a <strong> in a rich-text editor the event target is that <strong>, not the editable host, so checking the target alone skips the whole editor. The user then presses Cmd+B to embolden a task title and the sidebar jumps instead. The decision is exported as the pure function isEditableEventTarget so it can be unit tested directly.

Pass shortcutKey={false} to drop the shortcut, or shortcutKey="k" to rebind it.

Layout: in-flow rather than fixed

The comparable implementation in shadcn/ui lays out a fixed panel next to an equally wide spacer div. This component instead transitions its width in flow, because a fixed panel escapes any container that is not full screen (a documentation preview frame, a Viewport device frame, a split workspace) and pins itself to the viewport. The in-flow approach matches LayoutSider and AdminLayout and needs no measurement.

The trade-off: SidebarProvider must be the horizontal flex container, and Sidebar and SidebarInset must be its direct children. An extra wrapper div between them breaks the flex relationship.

Related

NavMenu · AdminLayout · Layout · Drawer · Tooltip · RouteTabs