Sidebar
The app navigation column, built from NavSection groups of NavItem rows, that collapses to a 64 px icon rail.
Overview
Sidebar holds an app's main navigation: a header, a primaryAction, the navigation itself as children, and a footer. It collapses from 248 px to a 64 px icon rail; icons and labels keep the same position in every row and in both widths, and collapsed items show their label in a tooltip.
Build the navigation from two parts:
- NavSection groups items, with an optional uppercase caption that can fold the section.
- NavItem is one destination: an icon, a label, and an optional count or end slot. It renders a link when it has an
hrefand a button otherwise.
The header, primaryAction and footer slots also accept a function of { collapsed }, for content that changes when the rail is collapsed.
Import
import { Sidebar } from '@unflowio/ui/components/Sidebar';
import { NavSection } from '@unflowio/ui/components/NavSection';
import { NavItem } from '@unflowio/ui/components/NavItem';Props
Sidebar
| Prop | Type | Default | Description |
|---|---|---|---|
collapsed | boolean | — | Collapsed state, controlled |
defaultCollapsed | boolean | — | Initial collapsed state, uncontrolled |
onCollapsedChange | (collapsed: boolean) => void | — | Called when the collapse toggle is used |
collapsible | boolean | true | Shows the collapse toggle |
header | SidebarSlot | — | Top slot, e.g. a workspace switcher |
primaryAction | SidebarSlot | — | Slot under the header, e.g. a "New project" button |
footer | SidebarSlot | — | Bottom slot, e.g. the account row |
loading | boolean | — | Replaces the items with skeleton rows |
loadingRows | number | 6 | Number of skeleton rows |
linkComponent | ElementType | 'a' | Renders NavItem links, e.g. next/link. A component can't be passed from a Server Component, so render the sidebar from a Client Component when you set it |
children | ReactNode | — | NavSections |
SidebarSlot is ReactNode | ((state: { collapsed: boolean }) => ReactNode).
NavSection
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | Small uppercase caption above the items. Also names the group |
collapsible | boolean | — | Lets the caption fold the section. Needs label |
open | boolean | — | Open state, controlled |
defaultOpen | boolean | — | Initial open state, uncontrolled |
onOpenChange | (open: boolean) => void | — | Called when the section folds or unfolds |
children | ReactNode | — | NavItems |
NavItem
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | Required. Row text |
icon | IconName | ReactNode | — | An icon name rendered with Icon, or any node (e.g. an Avatar) |
href | string | — | Renders a link. Without it the item is a button |
onClick | MouseEventHandler<HTMLElement> | — | Click handler |
active | boolean | — | Marks the current page with aria-current="page" |
count | number | — | Counter at the end of the row, or a dot on the icon when collapsed |
endSlot | ReactNode | — | Content at the end of the row |
disabled | boolean | — | Disables the item |
tooltip | string | label | Tooltip shown while the sidebar is collapsed |
linkComponent | ElementType | — | Overrides the sidebar's linkComponent for this item |
Basic usage
<Sidebar
header={({ collapsed }) => (collapsed ? null : <span className="text-sm font-semibold text-fg">Acme</span>)}
primaryAction={({ collapsed }) => (collapsed ? null : <Button label="New project" size="sm" fullWidth />)}
footer={<NavItem icon="bell" label="Notifications" href="/notifications" count={3} />}
>
<NavSection>
<NavItem icon="house" label="Home" href="/" active />
<NavItem icon="folder" label="Projects" href="/projects" />
</NavSection>
<NavSection label="Workspace" collapsible>
<NavItem icon="users" label="People" href="/people" />
</NavSection>
</Sidebar>Collapsed
<Sidebar defaultCollapsed>…</Sidebar>Use collapsed and onCollapsedChange to keep the state yourself, e.g. to remember it between visits.
Sections
Sections without a label render their items with no caption. Set collapsible={false} on the sidebar to hide the collapse toggle.
Loading
<Sidebar loading loadingRows={6} />Router links
Pass your router's link component once, on the sidebar, and every NavItem with an href renders through it:
'use client';
import Link from 'next/link';
<Sidebar linkComponent={Link}>…</Sidebar>Accessibility
- The sidebar is a
<nav>landmark named "Main" (translated). The collapse toggle hasaria-expandedand a translated label. - Collapsed items keep their label in the accessibility tree and show it in a tooltip on hover and focus.
- A labelled
NavSectionis arole="group"named by its caption; a collapsible one turns the caption into a button witharia-expandedandaria-controls. - The active item has
aria-current="page". An item with a count includes it in its accessible name (e.g. "Notifications, 3").