onCollapsedChange–
(collapsed: boolean) => voidCalled by the edge handle and the [ shortcut.
expandedIds–
string[]Controlled open tree groups (item ids).
defaultExpandedIds["projects"] with the default sections
string[]Tree groups open on first render.
onExpandedIdsChange–
(ids: string[]) => voidCalled when a tree group opens or closes (desktop and phone share the state).
query–
stringControlled search text for the built-in filter (used only without onSearch).
defaultQuery""
stringUncontrolled initial search text.
onQueryChange–
(query: string) => voidCalled as the search text changes.
accountMenuOpen–
booleanControlled account menu (desktop) / account sheet (phone).
defaultAccountMenuOpenfalse
booleanUncontrolled initial account menu state.
onAccountMenuOpenChange–
(open: boolean) => voidCalled when the account menu or sheet opens or closes.
drawerOpen–
booleanControlled phone drawer.
defaultDrawerOpenfalse
booleanUncontrolled initial drawer state.
onDrawerOpenChange–
(open: boolean) => voidCalled when the phone drawer opens or closes (menu button, scrim, swipe, Escape, choosing a row).
onSearch–
() => voidOpens your command palette from the search field and ⌘K / Ctrl+K. Without it, the field filters the sidebar's own items.
hotkeytrue
booleanBind ⌘K / Ctrl+K. It is handled only when onSearch is set (calls it) or the desktop search field is on screen (expands the rail and focuses it); otherwise the key passes through untouched (phone layout, hidden sidebar). Events another handler already prevented (GlassCommand's own ⌘K) are skipped, so the key never double-toggles. false also hides the ⌘K hint.
searchPlaceholder–
stringDeprecated alias of labels.search (wins when set).
labelsdefaultGlassSidebarLabels
Partial<GlassSidebarLabels>Every visible string and accessible name: search, searchButton(search, shortcut), expand, collapse, noMatches, nav, account, accountButton(name), openNavigation, closeNavigation, planTag, planUsage(unit), planRenews(date), upgrade.
linkComponent"a"
React.ElementTypeRenders every row, child, upgrade link and menu action that has an href. Pass Next's Link (or a wrapper around your router's Link) for client-side navigation. Receives href, className, style, children, onClick, aria-current, data-*.
userMara Quill
{ name: string; email: string; initials: string; avatarUrl?: string; online?: boolean }The account button and the menu's identity row.
planPro plan, 8/10 seats
{ name; tag?; used; total; unit; renewsOn; upgradeLabel?; upgradeHref?; onUpgrade? } | nullPlan card in the account menu; the usage bar fills when the menu opens. Pass null to hide it.
accountMenuAccount settings, Billing, Keyboard shortcuts, Sign out
{ id; label; icon; shortcut?; href?; onSelect?; tone? }[]Account menu actions. tone: "muted" for quiet items such as Sign out.
height"min(760px, calc(100dvh - 32px))"
number | stringHeight of the floating sidebar; the list scrolls inside with edge fades and a custom thumb. Use "100%" inside an app shell with a fixed-height parent.
width272
numberExpanded width in px; labels clip at width − 72.
collapsedWidth76
numberCollapsed rail width in px.
breakpoint720
numberViewport width in px where layout="auto" switches to the phone layout (CSS media query, no flash).
zIndex30
numberBase z-index of the fixed phone layer: top bar z, drawer scrim z+10, drawer z+11, account sheet scrim z+30, sheet z+31.
layout"auto"
"auto" | "desktop" | "mobile"Below breakpoint (720px) the sidebar becomes a glass top app bar, a left drawer (swipe to close) and an account bottom sheet (drag down to close). auto switches in CSS, so phones never flash the desktop layout. Add top padding (about 72px) to your page on phones for the fixed top bar.
mobileTitle–
stringTitle in the phone top bar. Defaults to the active item's label.
motion"full"
"full" | "subtle" | "off"full: the designed motion. subtle: calm curve, shorter, no staggers. off: instant. prefers-reduced-motion is always respected (150ms fades). "smooth" and "calm" from 1.0 still work.
soundtrue
boolean | "subtle"true plays Lumen cues when a GlassSoundProvider enables sound; false silences this instance; "subtle" plays at 55%. Without a provider nothing plays and the engine never loads.
theme"system"
"system" | "dark" | "light"system follows a .dark / .light class or data-theme on an ancestor (next-themes, shadcn), else the OS setting.
aria-label"Primary" (labels.nav)
stringAccessible name of the sidebar and its nav.
className–
stringAdded to the root of each layout (the desktop wrapper that carries the width, and the phone layer's display: contents wrapper).
style–
CSSPropertiesMerged last onto the same roots. Use it for CSS variables: --lg-<token> (e.g. --lg-lensBg, --lg-active, --lg-status) override the glass tokens for this sidebar, --glass-safe-top / --glass-safe-bottom / --glass-vw position the phone layer inside a frame or preview.
ref–
Ref<HTMLElement>The desktop <aside> (the drawer <aside> when layout="mobile").
...HTML attributes–
HTMLAttributes<HTMLElement>id, data-*, aria-*, role and event handlers go on the same <aside> as ref (only one, so ids stay unique).
