UnflowUI
Components

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 href and 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

PropTypeDefaultDescription
collapsedboolean—Collapsed state, controlled
defaultCollapsedboolean—Initial collapsed state, uncontrolled
onCollapsedChange(collapsed: boolean) => void—Called when the collapse toggle is used
collapsiblebooleantrueShows the collapse toggle
headerSidebarSlot—Top slot, e.g. a workspace switcher
primaryActionSidebarSlot—Slot under the header, e.g. a "New project" button
footerSidebarSlot—Bottom slot, e.g. the account row
loadingboolean—Replaces the items with skeleton rows
loadingRowsnumber6Number of skeleton rows
linkComponentElementType'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
childrenReactNode—NavSections

SidebarSlot is ReactNode | ((state: { collapsed: boolean }) => ReactNode).

PropTypeDefaultDescription
labelstring—Small uppercase caption above the items. Also names the group
collapsibleboolean—Lets the caption fold the section. Needs label
openboolean—Open state, controlled
defaultOpenboolean—Initial open state, uncontrolled
onOpenChange(open: boolean) => void—Called when the section folds or unfolds
childrenReactNode—NavItems
PropTypeDefaultDescription
labelstring—Required. Row text
iconIconName | ReactNode—An icon name rendered with Icon, or any node (e.g. an Avatar)
hrefstring—Renders a link. Without it the item is a button
onClickMouseEventHandler<HTMLElement>—Click handler
activeboolean—Marks the current page with aria-current="page"
countnumber—Counter at the end of the row, or a dot on the icon when collapsed
endSlotReactNode—Content at the end of the row
disabledboolean—Disables the item
tooltipstringlabelTooltip shown while the sidebar is collapsed
linkComponentElementType—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} />

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 has aria-expanded and a translated label.
  • Collapsed items keep their label in the accessibility tree and show it in a tooltip on hover and focus.
  • A labelled NavSection is a role="group" named by its caption; a collapsible one turns the caption into a button with aria-expanded and aria-controls.
  • The active item has aria-current="page". An item with a count includes it in its accessible name (e.g. "Notifications, 3").