Sidebar
Build desktop sidebar navigation that moves into a mobile drawer.
Anatomy#
Sidebar.Trigger can appear anywhere inside the root, and Sidebar.Rail sits directly between Panel and Inset. On mobile, Sidebar.Panel renders its regions inside an internal Drawer. Sidebar.Inset renders a <main> landmark by default, so keep page content inside it instead of adding another <main>.
Usage#
Use Sidebar for application-shell navigation that stays inline on desktop and moves into a mobile drawer. Use Drawer for a standalone swipe-to-dismiss drawer that is not a persistent layout region. Use NavigationMenu for a website header of links and panels.
Sidebar is both the state provider and the desktop layout root. Sidebar.Panel renders inline on
desktop and moves the same content into a mobile Drawer on smaller viewports.
Responsive navigation ownership#
Keep one navigation tree inside Sidebar.Panel. Put the application header outside the
frame, then place Sidebar.Trigger where users need to reveal or collapse navigation. A child that
must coordinate with the sidebar reads Sidebar.useContext() instead of keeping a second open
state.
Root open, defaultOpen, and onOpenChange drive whichever layout is active: the desktop panel or
the mobile drawer. Uncontrolled desktop and mobile states are remembered separately. defaultOpen
seeds both layouts, defaultOpen="desktop-only" seeds only the panel, and when omitted the desktop
panel starts expanded and the drawer starts closed. Switching layouts never calls onOpenChange and
never writes a controlled open. Leaving mobile closes an uncontrolled drawer, and returning to
desktop restores the desktop state. The trigger, the rail, and Escape or overlay dismissal of the
drawer all report through onOpenChange.
On mobile, a Sidebar.MenuButton with href closes the drawer when activated. Modified and
non-primary clicks, and clicks that call preventDefault(), leave it open. Set
closeOnSelect={false} to keep the drawer open after an href click, or closeOnSelect on a
button without href to close it.
When mobile is omitted, breakpoint (default 768) selects the layout through the
(max-width: ${breakpoint}px) media query, and the server renders the desktop layout. Pass mobile
to force either layout.
side ('left' or 'right') and variant ('default', 'floating', or 'inset') on the root
choose the viewport edge and chrome. Root classes and styles set defaults for the slots of every
part. On mobile, the sidebar renders inside a Drawer. Style the Sidebar regions through their own
slots; Sidebar overrides do not style the internal Drawer. See Theming for
nested Provider behavior.
Sidebar declares --mo-sidebar-width on its root. Pass a numeric width (controlled),
defaultWidth (uncontrolled), minWidth (default 224), or maxWidth (default 480) in pixels.
onWidthChange reports every width change. When none of the width props is set, the recipe fallback
var(--sidebar-width, clamp(14rem, 25%, 20rem)) applies, so you can also set the global
--sidebar-width in CSS or with presetMoraine. When collapsed, the desktop panel keeps its width
and slides out with a negative margin, so its content does not reflow during the transition.
The root uses h-full so it can sit inside a bounded container. For a viewport shell, pass
class="h-dvh" (or h-svh) on the root.
Call Sidebar.useContext() from a descendant for side, variant, isMobile, isOpen, state
('expanded' or 'collapsed'), setOpen, and toggle. Place a global application header outside
the frame. Pass translations (label for the mobile drawer, resize for the rail) to localize
the accessible names of one sidebar.
Resizable rail#
Place Sidebar.Rail directly between Sidebar.Panel and Sidebar.Inset to make the desktop
sidebar resizable; it renders nothing on mobile. Dragging the rail updates the pixel width live
between minWidth and maxWidth. Releasing a drag that changed the width calls onWidthCommit
once, and each keyboard resize calls it too. A click without movement toggles the sidebar, and
dragging below half of minWidth closes it; drag back to reopen. Set disabled on the rail to turn
off resizing and toggling. Because the root is a splitter scope, a nested Resizable inside
Sidebar.Inset whose handle has intersection and touches the rail cross-drags both.
| Key | Action |
|---|---|
Growth arrow (ArrowRight or ArrowLeft, follows geometry) |
Grows the panel by 16px. |
Growth arrow + Shift |
Grows the panel by 1px. |
| Opposite arrow | Shrinks the panel; clamps at minWidth, never closes. |
Home / End |
Sets the width to minWidth / maxWidth. |
Enter |
Toggles open; the only key that acts while closed. |
To persist desktop layout across reloads, control open and width from the app and store them in
a cookie inside onOpenChange and onWidthCommit. Do not use localStorage, which mismatches SSR
hydration.
Navigation menu#
Build labeled navigation with these parts:
Sidebar.Group: section container that holds a label and a menuSidebar.GroupLabel: section title; setas="h2"or another tag when the page needs a headingSidebar.Menu:<ul>list of the items of a groupSidebar.MenuItem:<li>that holds oneMenuButtonwith an optionalMenuAction, or aMenuSubSidebar.MenuButton: polymorphic button (button,awhenhrefis set, or a custom link throughas) withleadingandtrailingicon names andactive. It owns the hover, active, focus, and disabled styles. On a link,activealso setsaria-current="page"Sidebar.MenuAction: controls placed over the end of the item’s first row, such as a dropdown menu trigger. The button stays highlighted while the pointer is over the action. The button does not reserve space for the action, so addpe-8to aMenuButtonwhose label can run under itSidebar.MenuSub/MenuSubTrigger/MenuSubContent: collapsible sub-navigation built onCollapsible, placed inside aMenuItem.MenuSubtakesopen,defaultOpen,onOpenChange,disabled,transition(animates the height), andforceMount.MenuSubTriggerrenders aMenuButtonwith a chevron (trailing) that rotates while expanded.MenuSubContentrenders a nested<ul>ofMenuItems
Use DropdownMenu inside header, footer, or Sidebar.MenuAction for workspace
switchers and row actions. Those menus are actions, not the sidebar’s navigation tree.
Examples#
Cloud console shell#
Keep one navigation tree for desktop and mobile. Place the trigger in the main header so compact viewports can open the drawer.
Docs tree with collapsible sections#
Put a MenuSub inside a MenuItem for multi-level docs. The trigger only toggles its section,
so link the section’s pages from the nested items.
Inspector beside a document#
Use side="right" and variant="inset" for a properties panel next to a canvas or RFC.
Team switcher and account menu#
Put a workspace DropdownMenu in the header slot and an account menu in the footer.
Global topbar above the frame#
Keep brand, project picker, and alerts outside Sidebar. Let the frame fill the remaining
height.
Resize the explorer on desktop#
Sidebar.Rail between Panel and Inset resizes the sidebar in pixels. On mobile, the same content
moves into the Drawer and the rail disappears.
Force the mobile drawer#
Set mobile to render the slide-over navigation drawer at any viewport width, for example in a
touch-first layout.
API Reference#
Attributes#
data-mobiledata-sidedata-splitter-rootdata-variantdata-closeddata-expandeddata-resizingdata-activedata-draggingdata-disableddata-openProps#
Sidebar#
Renders a <div> element by default.
Panel#
Renders a <aside> element by default.
Rail#
Renders a <div> element by default.
Header#
Renders a <div> element by default.
Content#
Renders a <div> element by default.
Footer#
Renders a <div> element by default.
Inset#
Renders a <main> element by default.
Trigger#
Renders a <button> element by default.
Group#
Renders a <div> element by default.
GroupLabel#
Renders a <div> element by default.
Menu#
Renders a <ul> element by default.
MenuItem#
Renders a <li> element by default.
MenuButton#
Renders a <button> element by default.
MenuAction#
Renders a <div> element by default.
MenuSub#
Renders a <div> element by default.
MenuSubTrigger#
Renders a <button> element by default.
MenuSubContent#
Renders a <ul> element by default.