Tabsalternative
Use Tabs for in-page section navigationSidebar
Responsive navigation sidebar with collapsible desktop mode and mobile drawer behavior.
Setup
import { Sidebar } from '@fragments-sdk/ui';Examples
Default
Standard sidebar with navigation sections. The `active` prop highlights the current page.
Loading preview...
Collapsed
Icon-only collapsed state. Header shows only logo, tooltips appear on hover.
Loading preview...
With Badges
Navigation items with notification badges for counts or alerts.
Loading preview...
With Submenu
Nested navigation with expandable sections. Use defaultExpanded for initial state without manual state tracking.
Loading preview...
With Disabled Items
Some navigation items are disabled for permissions or feature flags.
Loading preview...
With Provider & External Trigger
SidebarProvider enables external triggers and keyboard shortcuts (Cmd/Ctrl+B).
Loading preview...
With asChild (Polymorphic)
Use asChild to render items as custom elements like Next.js Link or React Router NavLink.
Loading preview...
With Section Action
Section headers can include action buttons for quick actions like "Add Project".
Loading preview...
With Loading Skeleton
Show skeleton placeholders while navigation data is loading.
Loading preview...
With Rail Toggle
Add a Rail component for a subtle drag-handle style toggle at the sidebar edge. Hover to reveal, click to toggle.
Loading preview...
Offcanvas Collapsed
Offcanvas mode hides the sidebar completely when collapsed, but the toggle button remains visible as a floating button so the user can always re-expand.
Loading preview...
Props
| Prop | Type | Default | Description |
|---|---|---|---|
childrenRequired | node | Not set | Sidebar content (use Sidebar.Header, Sidebar.Nav, Sidebar.Section, etc.) |
collapsed | boolean | Not set | Icon-only mode for desktop (controlled) |
defaultCollapsed | boolean | false | Initial collapsed state (uncontrolled) |
onCollapsedChange | function | Not set | Called when collapsed state changes |
open | boolean | Not set | Mobile drawer open state (controlled) |
defaultOpen | boolean | false | Initial open state (uncontrolled) |
onOpenChange | function | Not set | Called when open state changes |
width | string | 240px | Width of expanded sidebar |
collapsedWidth | string | 56px | Width when collapsed |
position | enumleftright | left | Sidebar position |
collapsible | enumiconoffcanvasnone | icon | Collapse behavior mode |
style | object | Not set | — |
Usage Guidelines
When to use
- Primary app navigation with multiple sections
- Dashboard layouts requiring persistent navigation
- Admin interfaces with hierarchical menu structure
- Apps that need both mobile drawer and desktop sidebar
When not to use
- Simple websites with few pages (use header nav)
- Content-focused sites where navigation is secondary
- Single-page applications with no navigation needs
- Mobile-only apps where bottom navigation is preferred
Best practices
- Group related items into sections with clear labels
- Use icons for all items to support collapsed mode
- Limit nesting to 2 levels maximum
- Place most frequently used items at the top
- Use badges sparingly for notifications or counts
- The `active` prop on items should be controlled by your app based on current route
- Use `collapsedContent` on Header to show just a logo icon when collapsed
- Submenus are hidden when collapsed - use tooltips for navigation hints instead
- Use SidebarProvider to enable external triggers and keyboard shortcuts
- Use asChild with routing libraries (Next.js Link, React Router NavLink)
- Sidebar.Item and Sidebar.SubItem onClick handlers receive the click event object
- Use Sidebar.MenuSkeleton while loading navigation data
Accessibility
- Uses semantic <nav> element with aria-label
- aria-current="page" on active items
- aria-expanded on items with submenus
- Escape key closes mobile drawer
- Cmd/Ctrl+B keyboard shortcut toggles sidebar (when using SidebarProvider)
- Focus trap in mobile drawer mode
- Minimum 44px touch targets