Sidebar Primitive

Overview and decision boundary

Use Sidebar Primitive for a persistent collapsible page region while keeping routes, navigation data, menus, permissions, and persistence in consumer code.

Do not add route matching, navigation schemas, persistence, authorization, or account behavior to Core Sidebar.

Installation and imports

Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.

1pnpm dlx nerio add sidebar-primitive23import { SidebarContent, SidebarFooter, SidebarHeader, SidebarInset } from '@nerio-ui/ui';4import { Sidebar, SidebarProvider, SidebarRail, SidebarTrigger } from '@nerio-ui/ui/client';

Usage

1"use client";23import * as React from "react";4import { SidebarProvider } from "@nerio-ui/ui/client";56function PersistentSidebar({ children }: React.PropsWithChildren) {7  const [expanded, setExpanded] = React.useState(true);89  React.useEffect(() => {10    setExpanded(window.localStorage.getItem("sidebar-expanded") !== "false");11  }, []);1213  return (14    <SidebarProvider15      expanded={expanded}16      onExpandedChange={(nextExpanded) => {17        setExpanded(nextExpanded);18        window.localStorage.setItem("sidebar-expanded", String(nextExpanded));19      }}20    >21      {children}22    </SidebarProvider>23  );24}

1import { SidebarContent, SidebarInset } from "@nerio-ui/ui";2import { Button, Sheet, SheetBody, SheetContent, SheetHeader, SheetTitle, SheetTrigger, Sidebar, SidebarProvider } from "@nerio-ui/ui/client";34const navigation = [5  { label: "Overview", href: "/" },6  { label: "Projects", href: "/projects" },7];89// Resolve isMobile in consumer code with a hydration-safe media-query hook.10return isMobile ? (11  <Sheet>12    <SheetTrigger render={<Button>Open navigation</Button>} />13    <SheetContent side="left" size="sm">14      <SheetHeader><SheetTitle>Navigation</SheetTitle></SheetHeader>15      <SheetBody><ProductNavigation items={navigation} /></SheetBody>16    </SheetContent>17  </Sheet>18) : (19  <SidebarProvider>20    <Sidebar aria-label="Workspace sidebar">21      <SidebarContent><ProductNavigation items={navigation} /></SidebarContent>22    </Sidebar>23    <SidebarInset>...</SidebarInset>24  </SidebarProvider>25);

1import { SidebarContent, SidebarFooter, SidebarHeader, SidebarInset } from '@nerio-ui/ui';2import { Sidebar, SidebarProvider, SidebarRail, SidebarTrigger } from '@nerio-ui/ui/client';34<SidebarProvider defaultExpanded side="left">5  <Sidebar aria-label="Workspace sidebar">6    <SidebarHeader>Workspace</SidebarHeader>7    <SidebarContent>8      <nav aria-label="Workspace">...</nav>9    </SidebarContent>10    <SidebarFooter>...</SidebarFooter>11    <SidebarRail label="Toggle workspace sidebar" />12  </Sidebar>13  <SidebarInset>14    <SidebarTrigger label="Toggle workspace sidebar" />15    ...16  </SidebarInset>17</SidebarProvider>

Variants

Anatomy

States

Motion

• Width and content visibility use the Sidebar transition tokens.
• Reduced-motion preference removes the visible transition without changing state behavior.

Accessibility

• Sidebar renders complementary aside semantics by default; place a labelled navigation landmark inside SidebarContent when the content is navigation.
• SidebarTrigger and SidebarRail require a localized label and expose aria-expanded plus a stable aria-controls relationship.
• SidebarRail is vertically centered and occupies only --n-sidebar-rail-hit-area so adjacent Sidebar and SidebarInset content remains pointer reachable.
• SidebarContent forwards an HTMLDivElement ref, while SidebarInset preserves stable HTMLElement refs for its explicit div or main root.
• Collapsed Sidebar content is inert, hidden, and removed from pointer and keyboard interaction while SidebarRail remains reachable.
• State changes keep focus on the external trigger or rail and do not add roving focus or Arrow-key behavior to consumer navigation.
• Physical left and right placement, explicit text direction, reduced motion, forced colors, compact density, and safe-area padding are supported.
• Persistence and mobile behavior remain consumer-owned; compose Sheet explicitly for mobile navigation so only one interactive tree is rendered.

API

Implementation contract

Styling contract

Design notes

• Persistence is consumer-owned. Read storage before choosing controlled state and write from onExpandedChange.
• For mobile, render the shared navigation data inside Sheet instead of turning Sidebar into an AppShell.
• AppSidebar, workspace switching, nested navigation, route matching, account menus, badges, and permissions remain Pro or consumer responsibilities.

Do / do not

Related components

Tokens

These are the primary customization points. Override semantic or component tokens instead of changing component source.