{/* The sidebar is a drawer below md, so the trigger only shows there. */}
{section.label}
{section.rows.map(([term, value]) => (
{term}
{value}
))}
);
}
```
## API reference
### SidebarProvider
Holds the state and renders a flex row: put Sidebar and SidebarInset inside. Give it min-h-svh for a page shell, or a fixed height for a framed panel.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `collapsed` | `boolean` | — | Rail state when controlled. |
| `defaultCollapsed` | `boolean` | `false` | Initial rail state when uncontrolled. |
| `onCollapsedChange` | `(collapsed: boolean) => void` | — | Called when the rail is toggled. |
| `shortcut` | `string \| false` | `"b"` | ⌘ or Ctrl plus this key toggles the sidebar. Ignored inside contenteditable. Pass false to turn it off. |
### Sidebar
The panel. From md up it sits in the layout, sticky, as tall as the viewport or the provider, whichever is smaller. Below md it is an off-canvas drawer. It sets data-state="collapsed" | "expanded" and the group/sidebar class for styling your own content.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"left" \| "right"` | `"left"` | Which edge it sits on. For the right, render it after SidebarInset. |
| `collapsible` | `"rail" \| "none"` | `"rail"` | Allow collapsing to the 56px icon rail. |
| `color` | `NeonColor` | `inherited` | Palette name or hex. Falls back to --neon-accent, then cyan. |
### SidebarHeader / SidebarFooter
Fixed rows at the top and bottom. They clip their content to the rail; fade your own text with useSidebar().collapsed, e.g. collapsed && "md:opacity-0".
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | — | Classes for the row. |
### SidebarContent
The scrolling middle. Renders a nav labelled "Sidebar".
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | `"Sidebar"` | Name of the navigation landmark. |
### SidebarGroup
A list of items with an optional heading. Items must live in a group, including in the footer.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `ReactNode` | — | Heading above the items. In the rail it becomes a short divider. |
### SidebarItem
A row in a group. Renders a link with href, a button without, or your own element with asChild.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | — | 16px icon. It stays put while the sidebar collapses. |
| `href` | `string` | — | Renders an a instead of a button. |
| `active` | `boolean` | `false` | Marks the current page: aria-current="page" and the lit tube. |
| `badge` | `ReactNode` | — | Count or short tag at the end of the row. In the rail it becomes a dot on the icon. |
| `tooltip` | `ReactNode` | — | Text for the rail hover label. Defaults to the item's label. |
| `disabled` | `boolean` | `false` | Dims the row and blocks clicks. |
| `onClick` | `(event) => void` | — | Below md, a click also closes the drawer unless you call event.preventDefault(). |
| `asChild` | `boolean` | `false` | Merge onto the single child, such as your router's Link. The child's children become the label. |
### SidebarTrigger
An icon button that collapses or expands the sidebar, or opens the drawer below md. Children replace the icon.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `NeonColor` | `inherited` | Palette name or hex for the focus ring. |
### SidebarInset
The page next to the sidebar. A flex column that takes the remaining width. While the drawer is open it is inert.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | — | Classes for the page column, e.g. overflow-y-auto. |
### useSidebar()
Reads the nearest SidebarProvider. Throws outside one.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `collapsed` | `boolean` | — | Whether the sidebar is on the rail (md and up). |
| `setCollapsed` | `(collapsed: boolean) => void` | — | Collapse or expand. |
| `toggle` | `() => void` | — | What the trigger and the shortcut call: the rail on desktop, the drawer below md. |
| `isMobile` | `boolean` | — | True below md, where the sidebar is a drawer. False during server rendering. |
| `openMobile` | `boolean` | — | Whether the drawer is open. |
| `setOpenMobile` | `(open: boolean) => void` | — | Open or close the drawer. |
## Accessibility
- The trigger is a button named "Toggle sidebar" with aria-expanded, aria-controls pointing at the panel, and aria-keyshortcuts for ⌘B and Ctrl+B.
- The active item has aria-current="page". The tube is decorative and hidden from screen readers.
- On the rail the labels fade but stay in the accessibility tree, so every item keeps its name. The hover label is visual only and also appears on keyboard focus.
- The hover label closes on Escape, on scroll and when the pointer leaves the item.
- Below md the sidebar is a modal drawer: focus moves into it and Tab cycles inside it, Escape and the backdrop close it, the page behind is inert and stops scrolling, and focus returns to the trigger. The drawer renders into document.body, so no parent's z-index or transform can trap it.
- The width animation and the glide respect reduced motion.
## Source
`components/ui/sidebar.tsx`
```tsx
"use client";
import * as React from "react";
import { createPortal } from "react-dom";
import { AnimatePresence, motion, useReducedMotion } from "motion/react";
import { PanelLeft } from "@/components/ui/icons";
import { cn } from "@/lib/utils";
import { neonVars, type NeonColor } from "@/lib/neon";
/** The single element in `node`. Server Components can pass it as a lazy reference, which Children resolves. */
function resolveElement
(child) ? child : null;
}
type RenderProp = { asChild?: boolean; render?: React.ReactElement; nativeButton?: boolean; children?: React.ReactNode };
/**
* Base UI spells asChild as `render={}` plus `nativeButton`, and the shadcn CLI rewrites
* asChild into that form in base-* projects. Folds it back into asChild and children.
*/
function fromRenderProp
({ render, nativeButton, ...props }: P): Omit {
void nativeButton; // Only meaningful to Base UI.
if (!render) return props;
const children = props.children === undefined ? render : React.cloneElement(render, undefined, props.children);
return { ...props, asChild: true, children };
}
const EASE = [0.23, 1, 0.32, 1] as const;
const GLIDE = { duration: 0.3, ease: EASE };
const MOBILE_QUERY = "(max-width: 767.98px)";
// React 19 treats inert as a boolean; React 18 only renders it from a string.
const INERT = (Number.parseInt(React.version, 10) >= 19 ? { inert: true } : { inert: "" }) as React.HTMLAttributes;
const FOCUSABLE =
'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
type AnyRef = React.Ref | undefined;
function setRef(ref: AnyRef, value: T | null) {
if (typeof ref === "function") ref(value);
else if (ref) (ref as React.RefObject).current = value;
}
// React 19 moved `ref` into props; reading `element.ref` there logs a warning.
function getElementRef(element: React.ReactElement): AnyRef {
if (Number.parseInt(React.version, 10) >= 19) {
return (element.props as { ref?: React.Ref }).ref;
}
return (element as unknown as { ref?: React.Ref }).ref;
}
function subscribeToViewport(callback: () => void) {
const query = window.matchMedia(MOBILE_QUERY);
query.addEventListener?.("change", callback);
return () => query.removeEventListener?.("change", callback);
}
/** Below `md` the sidebar is an off-canvas drawer. The server renders the desktop layout. */
function useIsMobile() {
return React.useSyncExternalStore(
subscribeToViewport,
() => window.matchMedia(MOBILE_QUERY).matches,
() => false,
);
}
const subscribeNever = () => () => {};
function useMounted() {
return React.useSyncExternalStore(subscribeNever, () => true, () => false);
}
function isFocusVisible(element: Element) {
try {
return element.matches(":focus-visible");
} catch {
return true;
}
}
function matchesShortcut(event: KeyboardEvent, key: string) {
const target = key.toLowerCase();
if (event.key.toLowerCase() === target) return true;
// Non-Latin layouts and Option rewrite event.key, so fall back to the physical key.
if (/^[a-z]$/.test(target)) return event.code === `Key${target.toUpperCase()}`;
return false;
}
type SidebarContextValue = {
collapsed: boolean;
setCollapsed: (collapsed: boolean) => void;
/** Collapses or expands the sidebar; below `md` it opens or closes the drawer instead. */
toggle: () => void;
isMobile: boolean;
openMobile: boolean;
setOpenMobile: (open: boolean) => void;
sidebarId: string;
shortcut: string | false;
};
const SidebarContext = React.createContext(null);
function useSidebarContext(component: string) {
const context = React.useContext(SidebarContext);
if (!context) throw new Error(`<${component}> must be used inside .`);
return context;
}
/** Reads and controls the nearest SidebarProvider. */
function useSidebar() {
const context = React.useContext(SidebarContext);
if (!context) throw new Error("useSidebar must be used inside .");
return context;
}
type SidebarInstanceValue = {
layoutId: string;
side: "left" | "right";
/** Collapsed to the icon rail (md and up). */
rail: boolean;
hintsEnabled: boolean;
reduceMotion: boolean;
showHint: (element: HTMLElement, label: React.ReactNode, badge?: React.ReactNode) => void;
hideHint: (immediate?: boolean) => void;
};
const SidebarInstanceContext = React.createContext(null);
function useSidebarInstance(component: string) {
const context = React.useContext(SidebarInstanceContext);
if (!context) throw new Error(`<${component}> must be used inside .`);
return context;
}
export interface SidebarProviderProps extends React.HTMLAttributes {
/** Rail state when controlled. */
collapsed?: boolean;
/** Initial rail state when uncontrolled. */
defaultCollapsed?: boolean;
onCollapsedChange?: (collapsed: boolean) => void;
/** ⌘ (or Ctrl) plus this key toggles the sidebar. Pass false to turn the shortcut off. */
shortcut?: string | false;
}
const SidebarProvider = React.forwardRef(
(
{
className,
collapsed: collapsedProp,
defaultCollapsed = false,
onCollapsedChange,
shortcut = "b",
...props
},
ref,
) => {
const sidebarId = `${React.useId()}sidebar`;
const isMobile = useIsMobile();
const [uncontrolled, setUncontrolled] = React.useState(defaultCollapsed);
const [openMobile, setOpenMobile] = React.useState(false);
const collapsed = collapsedProp ?? uncontrolled;
// A drawer left open while the window widens past md shouldn't pop open again on the way back.
if (!isMobile && openMobile) setOpenMobile(false);
const setCollapsed = React.useCallback(
(next: boolean) => {
if (next === collapsed) return;
if (collapsedProp === undefined) setUncontrolled(next);
onCollapsedChange?.(next);
},
[collapsed, collapsedProp, onCollapsedChange],
);
const toggle = React.useCallback(() => {
if (isMobile) setOpenMobile((open) => !open);
else setCollapsed(!collapsed);
}, [isMobile, collapsed, setCollapsed]);
// The listener stays subscribed once; it always calls the latest toggle.
const toggleRef = React.useRef(toggle);
React.useEffect(() => {
toggleRef.current = toggle;
}, [toggle]);
React.useEffect(() => {
if (!shortcut) return;
const onKeyDown = (event: KeyboardEvent) => {
if (event.defaultPrevented || event.repeat || event.altKey || event.shiftKey) return;
if (!(event.metaKey || event.ctrlKey) || !matchesShortcut(event, shortcut)) return;
// Rich-text editors use ⌘B for bold.
const target = event.target;
if (target instanceof Element && target.closest('[contenteditable]:not([contenteditable="false"])')) return;
event.preventDefault();
toggleRef.current();
};
window.addEventListener("keydown", onKeyDown);
return () => window.removeEventListener("keydown", onKeyDown);
}, [shortcut]);
const context = React.useMemo(
() => ({
collapsed,
setCollapsed,
toggle,
isMobile,
openMobile,
setOpenMobile,
sidebarId,
shortcut,
}),
[collapsed, setCollapsed, toggle, isMobile, openMobile, sidebarId, shortcut],
);
return (
);
},
);
SidebarProvider.displayName = "SidebarProvider";
type Hint = {
label: React.ReactNode;
badge?: React.ReactNode;
x: number;
y: number;
neon: string;
};
export interface SidebarProps extends Omit, "color"> {
/** Palette name or any hex color. Inherits `--neon-accent` when omitted. */
color?: NeonColor;
side?: "left" | "right";
/** "rail" lets the sidebar collapse to a 56px icon rail; "none" keeps it open. */
collapsible?: "rail" | "none";
}
const Sidebar = React.forwardRef(
(
{
className,
style,
color,
side = "left",
collapsible = "rail",
children,
"aria-label": ariaLabel,
...props
},
ref,
) => {
const { collapsed, isMobile, openMobile, setOpenMobile, sidebarId } = useSidebarContext("Sidebar");
const panelRef = React.useRef(null);
const mergedRef = React.useCallback(
(node: HTMLDivElement | null) => {
setRef(ref, node);
panelRef.current = node;
},
[ref],
);
const instanceId = React.useId();
const reduceMotion = useReducedMotion() ?? false;
const mounted = useMounted();
const rail = collapsible === "rail" && collapsed;
const hintsEnabled = rail && !isMobile;
const drawerOpen = isMobile && openMobile;
const [hint, setHint] = React.useState(null);
const hideTimer = React.useRef(undefined);
// A stale hint must not reappear the next time the sidebar collapses.
const [hintsWereEnabled, setHintsWereEnabled] = React.useState(hintsEnabled);
if (hintsWereEnabled !== hintsEnabled) {
setHintsWereEnabled(hintsEnabled);
setHint(null);
}
const visibleHint = hintsEnabled ? hint : null;
const hintOpen = visibleHint !== null;
React.useEffect(() => () => window.clearTimeout(hideTimer.current), []);
const showHint = React.useCallback(
(element: HTMLElement, label: React.ReactNode, badge?: React.ReactNode) => {
window.clearTimeout(hideTimer.current);
const panel = panelRef.current;
if (!panel) return;
const item = element.getBoundingClientRect();
const bounds = panel.getBoundingClientRect();
setHint({
label,
badge,
x: side === "left" ? bounds.right + 10 : bounds.left - 10,
y: item.top + item.height / 2,
// The hint is portaled out of the sidebar, so it carries the color with it.
neon: getComputedStyle(panel).getPropertyValue("--neon").trim(),
});
},
[side],
);
const hideHint = React.useCallback((immediate = false) => {
window.clearTimeout(hideTimer.current);
if (immediate) setHint(null);
// A short grace period lets the hint glide to the next item instead of blinking.
else hideTimer.current = window.setTimeout(() => setHint(null), 80);
}, []);
React.useEffect(() => {
if (!hintOpen) return;
const close = () => setHint(null);
const onKeyDown = (event: KeyboardEvent) => {
if (event.key === "Escape") close();
};
window.addEventListener("scroll", close, true);
window.addEventListener("resize", close);
document.addEventListener("keydown", onKeyDown);
return () => {
window.removeEventListener("scroll", close, true);
window.removeEventListener("resize", close);
document.removeEventListener("keydown", onKeyDown);
};
}, [hintOpen]);
// The mobile drawer behaves like a modal: focus moves in, Escape closes, the page stops scrolling.
React.useEffect(() => {
if (!drawerOpen) return;
const panel = panelRef.current;
const restore = document.activeElement instanceof HTMLElement ? document.activeElement : null;
// Wait two frames: the panel is still visibility:hidden until its transition starts.
let frame = requestAnimationFrame(() => {
frame = requestAnimationFrame(() => {
const first = panel?.querySelector(FOCUSABLE);
(first ?? panel)?.focus({ preventScroll: true });
});
});
const onKeyDown = (event: KeyboardEvent) => {
if (event.defaultPrevented || !panel) return;
if (event.key === "Escape") {
event.preventDefault();
setOpenMobile(false);
return;
}
// SidebarInset is inert, but the rest of the page may not be: keep Tab inside the drawer.
if (event.key !== "Tab") return;
const focusable = Array.from(panel.querySelectorAll(FOCUSABLE)).filter(
(element) =>
!element.closest("[hidden], [inert]") &&
(typeof element.checkVisibility !== "function" || element.checkVisibility()),
);
if (focusable.length === 0) {
event.preventDefault();
panel.focus({ preventScroll: true });
return;
}
const first = focusable[0];
const last = focusable[focusable.length - 1];
const active = document.activeElement;
const outside = !(active instanceof Node) || !panel.contains(active);
if (event.shiftKey && (active === first || active === panel || outside)) {
event.preventDefault();
last.focus();
} else if (!event.shiftKey && (active === last || outside)) {
event.preventDefault();
first.focus();
}
};
const overflow = document.body.style.overflow;
document.body.style.overflow = "hidden";
document.addEventListener("keydown", onKeyDown);
return () => {
cancelAnimationFrame(frame);
document.removeEventListener("keydown", onKeyDown);
document.body.style.overflow = overflow;
if (restore?.isConnected) restore.focus({ preventScroll: true });
};
}, [drawerOpen, setOpenMobile]);
const instance = React.useMemo(
() => ({ layoutId: instanceId, side, rail, hintsEnabled, reduceMotion, showHint, hideHint }),
[instanceId, side, rail, hintsEnabled, reduceMotion, showHint, hideHint],
);
const nudge = reduceMotion ? 0 : side === "left" ? -4 : 4;
// Below md the drawer renders into document.body, so an isolated, transformed or z-indexed
// ancestor (a card, a preview frame) can't trap it under a sticky header. The portal leaves the
// accent behind, so it's read from where the Sidebar is mounted.
const portaled = isMobile && mounted;
const anchorRef = React.useRef(null);
const [inheritedAccent, setInheritedAccent] = React.useState(undefined);
React.useEffect(() => {
const anchor = anchorRef.current;
if (!portaled || color || !anchor) return;
setInheritedAccent(getComputedStyle(anchor).getPropertyValue("--neon-accent").trim() || undefined);
}, [portaled, color, openMobile]);
const panelStyle =
portaled && !color && inheritedAccent
? ({ "--neon-accent": inheritedAccent, ...style } as React.CSSProperties)
: style;
const drawer = (
<>
{drawerOpen && (
setOpenMobile(false)}
className="fixed inset-0 z-50 bg-black/60 md:hidden"
/>
)}