Components / navigation

Sidebar

The vertical navigation container for an app: a header (product and collapse toggle), Sidebar Items grouped in titled sections, and an optional footer (the signed-in account).

import { Sidebar } from '@basiiik/ui';

The snippet an agent gets

From get_component_snippet, with the required props filled in from the spec. Every snippet is type-checked against the library before it is shipped.

import { Sidebar, SidebarItem, SidebarSection } from '@basiiik/ui';

<Sidebar><SidebarSection title="Workspace"><SidebarItem href="/" selected>Home</SidebarItem></SidebarSection></Sidebar>

Collapsed is collapsed (controlled, with onCollapsedChange) or defaultCollapsed; collapsible shows the toggle. The items follow the sidebar through context.
Compose with: avatar, icon-button, sidebar-item.
Storybook: Navigation/Sidebar.

Props

Prop	Type	Notes
`collapsed`	`boolean`
`children` required	`ReactNode`
`header`	`ReactNode`
`footer`	`ReactNode`
`label`	`string`
`collapsible`	`boolean`
`onCollapsedChange`	`(collapsed: boolean) => void`

Other props

Prop	Type	What it does
`collapsedHeader`	`ReactNode`	What the header shows when collapsed, e.g. a logo mark.
`collapsedFooter`	`ReactNode`	What the footer shows when collapsed, e.g. the account's Avatar alone.
`defaultCollapsed`	`boolean`	Starting state when `collapsed` is not controlled.

States. Collapsed is collapsed (controlled, with onCollapsedChange) or defaultCollapsed; collapsible shows the toggle. The items follow the sidebar through context.

Native attributes such as className, id and data-* are forwarded to the root element.

Parts

`SidebarSection`

A group of SidebarItems, rendered as a list. title is optional and names the list; collapsed, it is read but not shown.

<SidebarSection title="Workspace"><SidebarItem href="/" selected>Home</SidebarItem></SidebarSection>

SidebarSection props

Prop	Type	What it does
`children` required	`ReactNode`	`SidebarItem`s. Each one is put in its own list item.
`title`	`string`	A short heading for the group. It names the list; when the sidebar is collapsed it is read but not shown.

Use it when

The main navigation of an app with five or more destinations, or destinations in groups
A workspace or settings area with its own sections

Do not use it when

A site with a few top-level pages (use Navbar)
Switching views inside one page (use Tabs)
Actions such as New or Export (use Button or DropdownMenu; a sidebar holds destinations)
Navigation on small screens without a menu (put the Sidebar in a Drawer opened from the Navbar menu button)

Rules for agents

Put every SidebarItem inside a SidebarSection; the section makes the list, and its title is optional
Mark exactly one item selected: the current page
Give every item an icon when the sidebar can collapse; collapsed items show only the icon
Use header for the product name or logo and footer for the signed-in account; pass collapsedHeader or collapsedFooter (a logo mark, the Avatar alone) to keep something visible when collapsed
Set collapsible to show the toggle; control it with collapsed and onCollapsedChange when the state must persist (remember it per user)
Keep one or two levels: sections of items, no nested sidebars

Avoid

Hand-building a sidebar from a <div>, links and a toggle button
Passing collapsed to each SidebarItem instead of to the Sidebar
SidebarItems placed directly in the Sidebar without a SidebarSection
Items without icons in a collapsible sidebar
Actions (New project, Log out) as SidebarItems; put them in the footer as a Button or a DropdownMenu
Two navigation landmarks with the same name on one page
A fixed pixel height on the Sidebar instead of letting it fill its parent

Writing the content

Section titles: one or two words in sentence case: "Workspace", "Account"
Item labels: short nouns: "Projects", "Settings"
Landmark label: what the navigation covers: "Main", "Project", "Settings"

Keyboard

Tab moves through the collapse toggle, then the items
Enter or Space on the toggle collapses or expands the sidebar
Enter on an item follows its link

Accessibility

The items sit in a <nav> landmark named by label (default "Main"); give each landmark on a page its own name
Each SidebarSection is a list named by its title, so a screen reader hears "Workspace, list, 3 items"
The collapse toggle has aria-expanded and aria-controls pointing at the nav, and its name says what it will do ("Collapse sidebar", "Expand sidebar")
Collapsed, section titles are visually hidden but still name their lists, and every item keeps its label as its accessible name and tooltip

Colour tokens it reads

color.bg.brand.defaultcolor.bg.brand.subtlecolor.bg.surfacecolor.border.defaultcolor.border.subtlecolor.icon.primarycolor.icon.secondarycolor.text.brandcolor.text.on-brandcolor.text.primarycolor.text.secondarycolor.text.tertiary

navigation 2 Figma variants Try it in the live demo