# Sidebar

App navigation: docked, inset or floating, a dark tone on a light page, and an icon rail with flyouts.

- Category: Navigation & Layout
- Page: https://wunderui.com/components/sidebar
- Tier: Core and Pro

## Install

Sidebar ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { Sidebar, DoubleSidebar, SidebarContext, SidebarContextValue, SidebarCountTone, SidebarCta, SidebarDot, SidebarDotProps, SidebarDotTone, SidebarEmpty, SidebarEmptyProps, SidebarFilter, SidebarFilterProps, SidebarFlyoutContent, SidebarGroup, SidebarGroupProps, SidebarHeading, SidebarItem, SidebarItemProps, SidebarItemSkeleton, SidebarNotification, SidebarProgressRing, SidebarProgressRingProps, SidebarProgressTone, SidebarRail, SidebarRailProps, SidebarSearch, SidebarSection, SidebarSectionGroup, SidebarSectionGroupProps, SidebarSeparator, SidebarState, SidebarStateOptions, SidebarStatus, SidebarSwitchItem, SidebarUsage, SidebarUsageHeaderTone, SidebarUsageProps, SidebarUser, SidebarWorkspace } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { LayoutDashboard, Inbox } from "lucide-react"
import { Sidebar, SidebarItem, SidebarSection } from "@wunderui/react"

export function AppSidebar() {
  return (
    <Sidebar aria-label="Primary" logo={<span className="text-sm font-semibold text-foreground">WunderUI</span>}>
      <SidebarSection aria-label="Main">
        <SidebarItem icon={<LayoutDashboard />} label="Dashboard" href="/dashboard" active />
        <SidebarItem icon={<Inbox />} label="Inbox" href="/inbox" count={3} />
      </SidebarSection>
    </Sidebar>
  )
}
```

Expected result: You see a 256 px column with the logo and two rows with 18 px icons: Dashboard selected in semibold, Inbox with a grey count pill. Collapsed, it becomes a 48 px icon rail.

## When to use

### Use Sidebar for

- The primary navigation of an app with more than a few sections, with groups, counts and a footer
- A navigation that folds to a 48 px icon rail, or two levels as a rail of areas next to a panel of pages
- A dark navigation on a light page, or a floating or inset sidebar on the app background

### Use something else

- [Navbar](https://wunderui.com/components/navbar) for a handful of links across the top, with mega menus and search
- [App Layout](https://wunderui.com/components/app-layout) for the frame that holds the sidebar, a bar and the content, and turns the sidebar into a drawer on small screens
- [Tabs](https://wunderui.com/components/tabs) for switching views inside one page

## Keyboard

Rows are native links, and groups, the rail handle and footer rows are native buttons, so the browser handles focus and activation. Arrow keys do nothing, since this is a list of links, not a menu.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves through the rows, the group buttons, the search trigger, the filter, the footer button and the rail handle in reading order. Focus shows as an indigo border with a 2 px ring. Rows in a closed group are not in the tab order. |
| `Enter` | On a row: follows the link. On a group: opens or closes it. On the rail handle: folds or unfolds the sidebar. In the filter: nothing. |
| `Space` | On a group, on the rail handle and on the footer buttons: the same as Enter. A link is not activated by Space: the browser scrolls instead. |
| `Esc` | In a rail flyout: closes it and returns focus to the group's icon. In the filter: clears the text and keeps focus in the field. |
| `Ctrl+B` or `⌘B` | Folds or unfolds the sidebar when you use `useSidebarState` and give its `bind` to the element around the sidebar. It works while focus is inside that element and is ignored in text fields. |

## Behavior

What the sidebar does when it is current, folded, scrolled or filtered, and what it leaves to you.

- **Current page:** The active row is marked as the current page, with the selected surface and semibold text. Hover uses the page tone, pressed the subtle one, and on a group the page row inside is selected.
- **Styles:** Docked is a full-height column with a rule, inset has no surface, and floating is a rounded surface with margin, border and shadow. The inverse tone makes only the sidebar dark.
- **Side:** Setting the side to right moves a docked sidebar's rule and the rail handle to the matching edge. A rail flyout opens on the opposite side.
- **Rail:** Collapsed makes the sidebar 48 px wide, and labels stay as hidden text so each link keeps its name. Counts become an 8 px red dot, and dots, tags, trailing nodes and row actions are hidden.
- **Rail flyout:** A group in the rail becomes an icon button that opens a popover with its expanded pages, named after the group, closing when a link is followed. You can turn it off and render your own.
- **Row action:** The action sits at the end of the row and appears on hover and focus, and always on touch screens. While shown, it replaces the count, status dot and trailing node.
- **Groups:** A group is a collapsible: a button and a panel that opens to its height, with chevron and panel sharing one duration and curve. A guide line can run along its pages, which are 32 px high.
- **Section group:** A section group adds a heading, which becomes a button when collapsible, with an optional action at its end. In the rail the heading hides and the rows always show.
- **Scrolling:** The rows scroll inside the sidebar while the logo row and footer stay. The scrolled edges fade out over 24 px.
- **Fold state:** The fold hook returns the state, a setter, a toggle and a binding, and reads a saved choice before first paint. If a fold hides the focused element, focus moves to the rail handle.
- **Container:** The sidebar has a fixed width of its own, 256 or 48 px. Below the layout's drawer breakpoint App Layout moves it into a drawer, and on its own it does not collapse.
- **Semantics:** An aside with one nav per section, rows as links and groups as disclosures. Icons, chevrons and dots are hidden from screen readers unless a status label names the dot.

## Motion

Every transition uses the motion tokens and changes only transform, opacity and colour, or the height of a group panel.

- **Rows:** Colours change quickly. Nothing moves.
- **Group panel:** The panel opens to its height with the content keeping its own height. The chevron turns 180 degrees with the same duration and curve.
- **Row action:** The action fades in quickly.
- **Press:** The group icon in the rail and the user button scale to 0.97 while pressed.
- **Fold:** The width changes at once with no transition, so the content never reflows through half-widths.
- **Reduced motion:** With reduced motion the group panel and chevron change without a transition, and the pressed scale is off. Colours still change, because they are not motion.

## Anatomy

- `Sidebar`: The navigation column, an aside 256 px wide or a 48 px icon rail when collapsed. It comes docked, inset or floating, can use dark tokens alone, and needs an aria-label.
- `Logo row`: The logo, or a full-width header row such as a logo with actions, at least 44 px high and able to match the top bar's height. Show one logo per screen: bar or sidebar.
- `SidebarSection`: A nav that holds a run of rows and groups. Use one per block of links and name each with an aria-label, since two unnamed navigations are indistinguishable.
- `SidebarItem`: A navigation link row, 36 px high (32 px inside a group), with the selected surface when active and the current-page mark for screen readers. It can carry an icon, count, dot, tag or action.
- `SidebarGroup`: A row that opens a set of pages. It is a disclosure, never a menu, and its pages take no icons, and in the rail it becomes an icon button with a flyout.
- `Footer`: A block under the rows with a top border, for the person, workspace or a usage card. It does not scroll with the rows.
- `SidebarRail`: A handle on the content edge that folds the sidebar with a click, Enter or Space, not a drag. On hover and focus a short grip appears, centred on the edge line.
- `SidebarHeading`: A 44 px caption above a run of rows. Hidden in the rail.
- `SidebarSectionGroup`: A labelled section of rows, optionally collapsible, with an action slot at the end of its heading. In the rail the heading hides and the rows stay.
- `SidebarSearch`: A search-shaped button, not an input, that opens your command palette. It shows the shortcut, Cmd K or Ctrl K, but does not bind the key.
- `SidebarFilter`: A filter field for a long list, with a clear button, and Escape clears it. Hidden in the rail.
- `SidebarEmpty`: A status line for a filtered list with no match.
- `SidebarItemSkeleton`: Placeholder rows while navigation loads. A status region announces Loading navigation, and the rows are hidden from screen readers.
- `SidebarUser`: The signed-in person: an avatar, a name and an email. It is static, or a full-width button with a click handler, and in the rail only the avatar shows.
- `SidebarWorkspace`: A button with an avatar, a name, a description and a chevron, for switching workspace or account.
- `SidebarUsage`: A small card for a limit or quota: a title, a progress bar and a footer line. A tone turns the title and bar amber or red, and it is hidden in the rail.
- `SidebarCta`: A full-width primary button for one call to action, such as Upgrade plan. Hidden in the rail.
- `SidebarSwitchItem`: A row with a label and a switch, such as Dark mode. The switch hides in the rail.
- `SidebarNotification`: A button row with an avatar, a title, a time and an unread dot. In the rail only the avatar shows.
- `SidebarProgressRing`: A 14 px progress ring used as a leading element. It is an image named by its percentage, with an optional extra word.
- `SidebarDot`: An 8 px coloured dot used as a leading element. Decorative, so say the meaning in the label.
- `SidebarFlyoutContent`: The popover of a group in the rail. It opens on the side away from the sidebar, shows the pages expanded, is named by the group label and closes when a link is followed.
- `DoubleSidebar`: Two-level navigation: a collapsed Sidebar for the areas beside a full Sidebar for the pages of one area. A flex wrapper with no logic of its own.
- `SidebarContext`
- `SidebarSeparator`
- `Resize`
- `Search`

## Best practices

### When to use

- Use it for the main navigation of an app with more than a few sections. For a handful of site links across the top use a Navbar, and for the frame that holds both use App Layout.

### Do

- Give every top-level row an icon. In the collapsed rail only the icon shows, and a row without one has nothing to click.
- Give each navigating row a real href and mark the current page as active. Without an href the row is a placeholder, so use a click handler that prevents the default for client-side routing.
- Name every section with an aria-label, and the sidebar itself when the page has more than one aside.
- Give group pages no icons. A group indents its pages under its own label and lists them in a flyout in the rail.
- Keep one level of nesting where you can. A group inside a group is only for a section that really has sub-sections.
- Put a count only on a row that has something to act on. In the rail it becomes a red dot, so the number must also appear in the page.
- In the footer, show the person or the workspace, not both. Pick the one the reader switches more often.
- Let people widen the sidebar with resizable (and widthStorageKey to remember it) instead of a hand-built handle; keep the limits 224 to 384.

### Don't

- Don't use a row for commands. It is a link, so use a button or a Dropdown Menu for actions such as Sign out.
- Don't put a logo in the sidebar and in the top bar of the same screen. One logo per screen.
- Don't count on the search button's shortcut hint, because it only shows the keys and binding them is up to you. The fold state hook binds Ctrl or Cmd plus B.

## API reference

### Sidebar

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  | `SidebarSection`, `SidebarSearch`, `SidebarFilter` and the other blocks. They scroll inside the sidebar. |
| collapsed | boolean | false | The 48 px icon rail. Labels stay in the accessibility tree. |
| defaultWidth | number | 256 | Starting width of a resizable sidebar (and the reset width). Default 256. |
| footer | ReactNode |  | A block pinned under the rows with a top border: the person, the workspace, a usage card. |
| header | ReactNode |  | Replaces `logo` with a full-width row, for example a logo with actions. |
| headerHeight | number \| string |  | The height of the logo or header row, in px or any CSS length. Set it to the height of the top bar so the two share one centre line; the aside then drops its top padding. |
| logo | ReactNode |  | The logo row at the start. In the rail pass a mark: a wordmark does not fit 48 px. |
| maxWidth | number | 384 | Default 384. |
| minWidth | number | 224 | Default 224. |
| onWidthChange | (width: number) => void |  | Each new width while dragging or with the keys. |
| rail | ReactNode |  | A `SidebarRail` rendered as a direct child of the aside, so it spans the full height. As a child of the rows it is clipped by their scroll area. |
| resizable | boolean | false | A handle on the content edge resizes the expanded sidebar: drag it, or focus it and use the arrow keys (16 px, Shift 64 px), Home and End for the limits, Enter or a double click for `defaultWidth`. |
| side | "left" \| "right" | "left" | `left` (default) or `right`. A docked sidebar draws its rule on the content side. |
| tone | "default" \| "inverse" | "default" | `default`, or `inverse` for a dark navigation on a light page. |
| variant | "docked" \| "inset" \| "floating" | "docked" | `docked` (default), `inset` or `floating`. |
| width | number |  | Controlled width in px of a resizable sidebar. |
| widthStorageKey | string |  | Remembers the width in localStorage under this key. |

Also accepts React.HTMLAttributes attributes.

### DoubleSidebar

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  | The sidebar of the pages of one area. |
| className | string |  | Extra classes for the wrapper. |
| rail | ReactNode |  | The collapsed sidebar of the areas. |

### SidebarContext

| Prop | Type | Default |
|---|---|---|


Also accepts React.ProviderProps attributes.

### SidebarCta

| Prop | Type | Default |
|---|---|---|


Also accepts React.ButtonHTMLAttributes attributes.

### SidebarDot

| Prop | Type | Default | Description |
|---|---|---|---|
| tone* | "warning" \| "error" \| "success" \| "info" \| "purple" \| "pink" \| "orange" \| "primary" |  | The colour of the dot: `primary`, `success`, `warning`, `error`, `info`, `purple`, `orange` or `pink`. |

### SidebarEmpty

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  | The sentence to show, for example `No project matches “Zeta”.` |

Also accepts React.HTMLAttributes attributes.

### SidebarFilter

| Prop | Type | Default | Description |
|---|---|---|---|
| onValueChange* | (value: string) => void |  | Called with the new text. Escape and the clear button call it with an empty string. |
| value* | string |  | The text in the field. |
| label | string |  | The accessible name. Defaults to the placeholder without the ellipsis. |
| placeholder | string | "Filter…" | The placeholder. `Filter…` by default. |

Also accepts React.HTMLAttributes attributes.

### SidebarFlyoutContent

| Prop | Type | Default | Description |
|---|---|---|---|
| align | "center" \| "end" \| "start" | 'center' | How the flyout lines up with the trigger: `start`, `center` or `end`. `start` in a group. |
| anchor | Element \| null \| VirtualElement \| React.RefObject<Element \| null> \| (() => Element \| VirtualElement \| null) |  | Another element to anchor to instead of the trigger. |
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the flyout. |
| finalFocus | boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => void \| boolean \| HTMLElement \| null) |  | Which element takes focus when it closes. |
| initialFocus | boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => void \| boolean \| HTMLElement \| null) |  | Which element takes focus when the flyout opens. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the rendered element. |
| side | "left" \| "right" \| "bottom" \| "top" \| "inline-end" \| "inline-start" | 'bottom' | Which side of the trigger the flyout opens on. The group sets it opposite the sidebar. |
| sideOffset | number \| OffsetFunction | 0 | The distance from the trigger in px. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline styles for the flyout. |

Also accepts React.HTMLAttributes attributes.

### SidebarGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  | `SidebarItem` pages without icons. |
| label* | ReactNode |  | The text of the group's button. |
| active | boolean |  | One of the pages is the current page. The label turns quiet-bold; the page row carries the selected state. |
| ariaLabel | string |  | The accessible name of the rail button when it needs more than the label. |
| className | string |  | Extra classes for the group. |
| count | number |  | A number in a pill in the group's row. |
| countTone | "warning" \| "error" \| "success" \| "primary" \| "neutral" | "neutral" | The tone of the count pill. `neutral` by default. |
| defaultOpen | boolean |  | Starts open when uncontrolled. |
| guide | boolean |  | Draws a line along the pages. Nested groups inherit it unless they set their own. |
| icon | ReactNode |  | A 18 px icon, the only part of the group the rail shows. |
| leading | ReactNode |  | Replaces the icon. |
| onOpenChange | (open: boolean) => void |  | Called with the new open state. |
| open | boolean |  | Controls the open state. |
| railFlyout | boolean | true | Shows the flyout of pages in the rail. `true` by default; `false` hides the group so you can render your own. |
| status | "warning" \| "error" \| "success" \| "info" \| "neutral" |  | A status dot in the group's row. |
| statusLabel | string |  | The accessible name of the status dot. |
| tooltip | boolean | true | Shows a tooltip on the rail button. `true` by default. |

### SidebarHeading

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  | The caption text. |

### SidebarItem

| Prop | Type | Default | Description |
|---|---|---|---|
| label* | ReactNode |  | The text of the row. It stays in the accessibility tree in the rail. |
| action | ReactNode |  | A node shown on hover and focus, usually an icon button that opens a menu. A sibling of the link. |
| active | boolean |  | The current page: `aria-current="page"` and the selected surface. |
| count | number |  | A number in a pill at the end. In the rail a red dot, with the number in the accessible name. |
| countTone | "warning" \| "error" \| "success" \| "primary" \| "neutral" | "neutral" | `neutral` (default), `primary`, `success`, `warning` or `error`. |
| icon | ReactNode |  | A 18 px icon. Required for a top-level row: it is all the rail shows. |
| leading | ReactNode |  | Replaces the icon: a dot, a progress ring, an avatar. |
| status | "warning" \| "error" \| "success" \| "info" \| "neutral" |  | A 6 px dot at the end: `success`, `warning`, `error`, `info` or `neutral`. |
| statusLabel | string |  | The accessible name of the dot. Without it the dot is decorative; give it a name when the colour carries meaning. |
| tag | ReactNode |  | A small outlined word after the label, such as New or Beta. |
| tooltip | boolean | true | Shows the label as a tooltip in the rail. `true` by default. |
| trailing | ReactNode |  | Any node at the end of the row. Hidden in the rail. |

Also accepts React.AnchorHTMLAttributes attributes.

### SidebarItemSkeleton

| Prop | Type | Default | Description |
|---|---|---|---|
| count | number | 5 | The number of placeholder rows. Five by default. |

### SidebarNotification

| Prop | Type | Default | Description |
|---|---|---|---|
| avatar* | ReactNode |  | The avatar at the start. The only part the rail shows. |
| title* | ReactNode |  | What happened, one line. |
| className | string |  | Extra classes for the row. |
| onClick | () => void |  | Called when the row is pressed. |
| time | ReactNode |  | When, in tertiary text. |
| unread | boolean |  | Shows the unread dot. |

### SidebarProgressRing

| Prop | Type | Default | Description |
|---|---|---|---|
| value* | number |  | The progress, 0 to 100. It is in the accessible name. |
| label | string |  | A word added to the accessible name, such as `at risk`. |
| size | number | 14 | The diameter in px. 14 by default. |
| tone | "warning" \| "error" \| "success" \| "info" \| "default" \| "purple" | "default" | `default`, `success`, `warning`, `error`, `info` or `purple`. |

### SidebarRail

| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | "Toggle sidebar" | The accessible name of the handle. `Toggle sidebar` by default. |
| onToggle | () => void |  | Called when the handle is pressed. Fold the sidebar here. |
| tabIndex | number |  | The tab order of the handle. `0` by default; `-1` takes it out of the tab order when another control folds the sidebar. |

### SidebarSearch

| Prop | Type | Default | Description |
|---|---|---|---|
| placeholder | string | "Search…" | The text of the trigger. The accessible name is this text without the ellipsis. |
| shortcut | string | "⌘K" | The key hint, `⌘K` by default. Off a Mac it reads `Ctrl+K`. Display only. |

Also accepts React.ButtonHTMLAttributes attributes.

### SidebarSection

| Prop | Type | Default |
|---|---|---|


Also accepts React.HTMLAttributes attributes.

### SidebarSectionGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  | The rows, each wrapped in a list item. |
| label* | ReactNode |  | The heading of the section. |
| action | ReactNode |  | A node at the end of the heading, such as a New project button. |
| collapsible | boolean | false | Makes the heading a button that opens and closes the rows. Off by default; always open in the rail. |
| defaultOpen | boolean |  | Starts open when uncontrolled and collapsible. |
| onOpenChange | (open: boolean) => void |  | Called with the new open state. |
| open | boolean |  | Controls the open state. |

### SidebarSeparator

| Prop | Type | Default |
|---|---|---|


### SidebarSwitchItem

| Prop | Type | Default | Description |
|---|---|---|---|
| checked* | boolean |  | Whether the switch is on. |
| label* | ReactNode |  | The text of the row. |
| onCheckedChange* | (checked: boolean) => void |  | Called with the new value. |
| className | string |  | Extra classes for the row. |
| icon | ReactNode |  | An icon at the start. Shown in the rail. |

### SidebarUsage

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | string |  | The name of the quota, and the label of the progress bar. |
| value* | number |  | The amount used, from 0 to `max`. |
| ariaLabel | string |  | The accessible name of the bar when the title is not enough. |
| description | string |  | A short value at the end of the title line, such as `8.4 of 10 GB`. |
| footer | ReactNode |  | A line under the bar in tertiary text. |
| header | ReactNode |  | Content of a tinted band at the top of the card, such as `Trial ends in 3 days`. |
| headerTone | "warning" \| "error" \| "success" \| "info" \| "purple" \| "primary" \| "neutral" | "neutral" | The tint of the band. `neutral` by default. |
| max | number | 100 | The limit. `100` by default. |
| striped | boolean | false | Fills the bar with static diagonal stripes. |
| tone | "default" \| "warning" \| "error" | "default" | `default`, `warning` or `error`: the title and the bar turn amber or red. |

### SidebarUser

| Prop | Type | Default | Description |
|---|---|---|---|
| name* | string |  | The person's name. It is the accessible name of the button. |
| avatar | ReactNode |  | The avatar at the start. The only part the rail shows. |
| className | string |  | Extra classes for the row. |
| email | string |  | A second line in tertiary text. |
| onClick | () => void |  | Makes the whole row a button. |
| trailing | ReactNode |  | A node at the end, such as a menu button. Hidden in the rail. |

### SidebarWorkspace

| Prop | Type | Default | Description |
|---|---|---|---|
| avatar* | ReactNode |  | The avatar or logo of the workspace. |
| name* | ReactNode |  | The workspace name. |
| className | string |  | Extra classes for the button. |
| description | ReactNode |  | A second line, such as the number of members. |
| onClick | () => void |  | Called when the row is pressed, usually to open a switcher. |

## Examples

### Side: left or right

### Rows: plain, count, status, tag, action, leading

### Groups: a group, a guide line, nested, a section

### Slots: search, filter, workspace, user, usage

### Rail: tooltips, a flyout, a double sidebar

### Loading and no match

## In context

### Workspace navigation: search, counts, a group and the person

The current row is marked as the current page and gets the selected surface. Tab walks the rows in order and Enter follows the focused one; the links stay on the page here.

### A rail you can fold with Ctrl+B and that remembers it

The hook holds the collapsed state, saves it and binds Ctrl+B (⌘B on a Mac) on the element you give it, ignoring fields. If a collapse hides the focused row, focus moves to the rail handle.

### Project list: filter, row actions and no match

The filter narrows the list as you type and Escape clears it. A row action shows on hover and focus and replaces the count or status, and when nothing matches a status line says so.

### Double sidebar: areas in a rail, pages in a panel

Two levels at a glance. The rail holds the top-level areas with tooltips and the panel holds the pages of the current area: pick an area, then a page.

## For AI agents

`get_component("sidebar")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
