Sidebar navigation for app shells, with clear active states and optional search. Use it to give users steady orientation.
Default usage you can copy and adapt.
Expanded sidebar with a current page highlight and a simple search flow.
Use button-trigger search when results need more space than an inline input.
Icon-only rail. Labels move into tooltips and item badges become a dot, so a notification count is not lost on collapse.
The props you are most likely to need, with types and defaults.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| mode | 'expanded' | 'collapsed' | No | expanded | Sidebar display mode |
| layout | 'rail' | 'card' | No | rail | Rail attaches to the viewport edge; card is a rounded floating panel on a soft surface |
| items | SidebarNavigationItem[] | No | [] | Primary and secondary sidebar items; optional section groups primary rows under headings |
| currentPath | string | No | — | Active route path used for selected styling |
| activePrimaryHref | string | No | — | Parent nav href to highlight when currentPath is a deeper leaf |
| ariaLabel | string | No | Sidebar navigation | Accessible name for the nav landmark |
| class | string | No | — | Extra classes, merged last so they win |
| className | string | No | — | Deprecated alias for class |
| logoSrc | string | No | — | Optional logo image URL |
| logoAlt | string | No | — | Accessible label for the logo image |
| brandName | string | No | — | Optional product name beside the logo |
| showProfile | boolean | No | true | Render the account row in the footer |
| profileName | string | No | Zabi | Account display name |
| profileEmail | string | No | hello@zabi.dev | Account secondary line |
| profileInitials | string | No | ZA | Avatar initials fallback |
| showSearch | boolean | No | true | Render the search affordance |
| searchMode | 'input' | 'button' | No | input | Inline input, or a button that opens your own panel |
| searchPlaceholder | string | No | Search... | Placeholder, and the button label in trigger mode |
| searchValue | string | No | — | Bindable search term; filters items in input mode |
| searchTriggerIcon | Component | No | Command | Trigger icon in button mode or when collapsed |
| searchTriggerVariant | ButtonVariant | No | outline | Button variant for the search trigger |
| searchTriggerSize | SizeVariant | No | sm | Button size for the search trigger |
| showLogout | boolean | No | true | Render the logout row |
| logoutLabel | string | No | Logout | Logout row label |
| showThemeToggle | boolean | No | true | Render the light/dark toggle |
| lightModeLabel | string | No | Light mode | Theme toggle label |
| isLightMode | boolean | No | false | Bindable theme toggle state |
| emptyStateTitle | string | No | Create your first navigation item | Heading when there are no items |
| emptyStateDescription | string | No | Add your first sidebar item so users can start navigating your product. | Body copy when there are no items |
| emptyStateActionLabel | string | No | Add navigation item | Call to action when there are no items |
| onNavigate | (item, event) => void | No | — | Fires on item click; call preventDefault for client routing |
| onSearchClick | () => void | No | — | Fires when the search trigger is pressed (button mode) |
| onLogout | () => void | No | — | Fires when logout is pressed |
| onThemeToggle | (next: boolean) => void | No | — | Fires with the next light-mode value |
| onEmptyStateAction | () => void | No | — | Fires when the empty-state action is pressed |
| onProfileClick | (event?) => void | No | — | Fires when the account row is pressed |
| profilePanelOpen | boolean | No | false | Whether your account panel is open (drives aria-expanded) |
| profilePanelControlsId | string | No | — | Id of your account panel, for aria-controls |
| profilePanel | Snippet | No | — | Snippet rendered as the account panel |