Sidebar

The app sidebar an AI product needs: a workspace switcher at the top, the main items with counts and shortcuts, headed sections that fold, a recent list (chat history) with rename, pin and delete, and an account menu at the bottom. ⌘B (Ctrl+B) folds it to an icon rail, where one tooltip glides between the icons as on Nav rail. Below 768px it leaves the layout and opens as a drawer from a button in the page's header.

The current item is marked with Tabs' flat pill, and when it changes the pill flies from the old row to the new one. Behavior comes from Base UI through the kit: the menus are Dropdown menu, the phone drawer is Drawer, and the rail's tooltip is Nav rail's NavRailTooltipGroup.

<SidebarProvider collapsed={collapsed} onCollapsedChange={setCollapsed}>  <div className="app">    <Sidebar      aria-label="Acme"      value={page}      onValueChange={setPage}      header={        <SidebarSwitcher mark={<AcmeMark />} name="Acme">          <MenuRadioGroup label="Workspaces" value={workspace} onValueChange={setWorkspace}>            <MenuRadioItem value="acme">Acme</MenuRadioItem>            <MenuRadioItem value="labs">Acme Labs</MenuRadioItem>          </MenuRadioGroup>          <MenuSeparator />          <MenuItem>Workspace settings</MenuItem>        </SidebarSwitcher>      }      items={[        { id: "new", label: "New chat", icon: <ComposeIcon /> },        { id: "search", label: "Search", icon: <Icon name="search" />, shortcut: "K" },        { id: "automations", label: "Automations", icon: <BoltIcon />, badge: 3 },      ]}      sections={[        {          id: "projects",          label: "Projects",          collapsible: true,          items: [            { id: "launch", label: "Website relaunch", icon: <FolderIcon />, items: [              { id: "checklist", label: "Launch checklist" },            ] },          ],        },      ]}      recent={{        items: chats,        loading: chatsLoading,        loadingLabel: "Loading chats…",        empty: <><p>No chats yet</p><p>Chats you start show up here.</p></>,        onRename: (id, title) => api.rename(id, title),        onPinnedChange: (id, pinned) => api.pin(id, pinned),        onDelete: (id) => api.remove(id),        showAll: { label: "All chats", href: "/chats" },      }}      footer={        <SidebarAccount avatar={<Avatar name="Ana Ruiz" size={24} decorative />} name="Ana Ruiz" detail="Pro plan">          <MenuItem>Settings</MenuItem>          <MenuSeparator />          <MenuItem>Log out</MenuItem>        </SidebarAccount>      }    />    <main>      <header>        <SidebarToggle />      </header>      …    </main>  </div></SidebarProvider>

Lay the sidebar and the page out in a row (display: flex, or a grid with an auto column); the sidebar sets its own width and the page takes the rest. It fills its container's height.

When to use it

• The frame of an app with more than a handful of places: the main areas, projects or folders, and a history people come back to.
• A chat product: new chat and search at the top, recent chats below, pinned ones above them.
• When the labels matter. Written labels are faster to scan than icons, and the rail is there for people who want the width.

When not to

• Three to seven sections and nothing else: use Nav rail, which is all icons and takes less room.
• Navigation inside one page: tabs or a segmented control.
• A settings screen's list of categories: a plain list of links in the page.
• A second sidebar inside the first. Nest one level, in sections; deeper trees belong on a page of their own.

Parts

Props

recent takes items ({ id, title, href?, pinned?, meta? }[]), loading, loadingLabel, empty, label ("Recent"), pinnedLabel ("Pinned"), onRename, onPinnedChange, onDelete and showAll ({ label, href } or { label, onClick }). Each handler you pass adds its row to the "…" menu. Pinned chats list under their own heading, above the rest. meta is quiet detail at the row's end, a relative time or a small AvatarGroup, in the subtle color; the "…" takes its place while it shows, and on touch screens, where the "…" always shows, it's left out.

onRename can return a promise: the field holds and shimmers until it settles, and a rejection's message shows under it, with the text kept. onDelete deletes at once; confirm in a dialog or offer Undo in a toast if it can't be undone.

An item with href renders a link (pressing it also calls onValueChange); without one it's a button. A group row is a disclosure, not a link. badge is an unread count: 0 hides it, over 99 it reads 99+. Ids must be unique across items, sections and the recent list, since one value marks the current one.

Layout

Everything lines up on one column: each icon sits where it would be centered in the collapsed capsule, so folding the sidebar never moves an icon. Recent titles and headings start on the icons' left edge. The page beside it should be one surface step up (--ui-surface on the --ui-canvas sidebar), with no line between them: the change of surface is the edge.

States

Motion

Nothing reflows while the sidebar folds: rows narrow with it, so the current pill becomes the rail's capsule, while the sections and recent list are held at the open width and fade before the edge reaches them. Labels leave in the first 120ms and come back once the width is most of the way open, so no word is read while it moves. The width eases like a height (Chat app's sidebar does the same); the pill flies like Tabs', stretching from one row to the next. It only flies between rows of the same width that are both on screen; otherwise it moves at once.

Under prefers-reduced-motion: reduce the width, labels, groups and removals change at once, the pill jumps, and the tooltip swaps in place.

Accessibility

• A nav landmark named by aria-label, around a list of links or buttons; the current one has aria-current="page". An item with a badge reads "Automations, 3 new".
• Tab visits every control in order, the "…" buttons included. Up and Down move between rows, Home and End to the first and last, skipping what's folded away.
• Folding headings and groups are buttons with aria-expanded and aria-controls; a folded list is inert, and so is the hidden part of the collapsed sidebar, so focus never lands on something you can't see.
• Collapsed, every icon keeps its accessible name (the label is still in the row, only transparent); the tooltip is a visual echo and aria-hidden.
• Shortcuts are in aria-keyshortcuts ("Meta+K Control+K"). The toggle says what it will do ("Collapse sidebar", "Expand sidebar", "Open sidebar"), with aria-expanded and aria-controls.
• The menus are Base UI menus: arrow keys, typeahead, Escape back to the trigger. Each "…" is named for its chat: "Actions for Board update outline".
• Rename: Enter saves, Escape cancels (and doesn't close a drawer around it), leaving the field saves. Focus returns to the row. After a delete, focus moves to the next chat.
• Titles and names carry dir="auto", so a Hebrew chat title reads right in an English sidebar and an English one in a Hebrew sidebar.
• The phone drawer traps focus and returns it to the toggle on close.

Before / after

Before: a column of links with an active class, a hand-rolled collapse that animates width and rewraps every label on the way, title attributes as tooltips, and a delete that removes the row in one frame.

<aside className={collapsed ? "sidebar collapsed" : "sidebar"}>  {pages.map((p) => (    <a key={p.id} href={p.href} title={collapsed ? p.label : undefined} className={p.id === page ? "active" : ""}>      {p.icon} {!collapsed && p.label}    </a>  ))}  <button onClick={() => setCollapsed(!collapsed)}>«</button></aside>

After:

<SidebarProvider>  <Sidebar aria-label="Acme" items={pages} value={page} onValueChange={setPage} recent={{ items: chats }} />  <main>    <SidebarToggle />  </main></SidebarProvider>