Sidebar
ProThe navigation column of an app: sections, groups and rows with counts, a footer for the person or workspace, and a 48 px icon rail with tooltips and flyouts.
Playground
Dashboard
Dashboard
Dashboard
Dashboard
Dashboard
Dashboard
Dashboard
Dashboard
Installation
Sidebar comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
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"Then use it:
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 for
- Navbar for a handful of links across the top, with mega menus and search
- 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 for switching views inside one page
Side
The sidebar sits on the left or the right. A docked sidebar draws its rule on the content side, so a details sidebar on the right keeps its rule on its start edge.
Dashboard
The rule sits on the content side.
Ticket 1,842
A details sidebar on the right: the rule moves to the content side.
Rows
A row is a link of 36 px, or 32 px inside a group, with an optional count, status dot, tag, leading mark or action. In the rail a count turns into a red dot.
Click a row to make it current.
Hover or focus a row: its label is the tooltip.
Click a row to make it current.
In the rail a count becomes a red dot; the number stays in the accessible name.
Click a row to make it current.
Hover or focus a row: its label is the tooltip.
Click a row to make it current.
Hover or focus a row: its label is the tooltip.
Hover or focus a row: the action replaces the count or status.
The row action only exists in the expanded sidebar.
Click a row to make it current.
Hover or focus a row: its label is the tooltip.
Groups
A group is a disclosure, never a menu, and its pages take no icons. A section group adds a heading and, if you want, a collapse and an action.
A group is a disclosure: Enter or Space opens and closes it.
A group is a disclosure: Enter or Space opens and closes it.
A group is a disclosure: Enter or Space opens and closes it.
A group is a disclosure: Enter or Space opens and closes it.
Slots
Above the rows: a search trigger, with its shortcut in one key cap (⌘ K or Ctrl K by platform, shortcut sets another), or a filter. Below them in the footer: the workspace, the person, or a usage card with one call to action.
Rail
Collapsed, the sidebar is a 48 px rail: every row needs an icon and a group becomes an icon button with a flyout. A double sidebar puts the areas in a rail next to the pages of one area.
Hover or focus an icon for its tooltip. The handle at the edge, or Enter on it, opens the sidebar.
Press the Projects icon: its pages open in a flyout. Escape closes it.
Projects
The rail holds the areas; the panel holds the pages of one area.
Loading and no match
The skeleton keeps the height of the rows while navigation loads. A filter without a match says so in a status line.
The skeleton announces Loading navigation and keeps the height of five rows.
A filter with no match says so in a status line.
Keyboard interactions
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.
- TaborShift+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+Bor⌘B
- Folds or unfolds the sidebar when you use and give its to the element around the sidebar. It works while focus is inside that element and is ignored in text fields.
Behavior and motion
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
The figure marks a docked sidebar with a group, a footer and the rail handle. The other parts are optional blocks you place in the sidebar, the footer or the rows.
- 1data-slot="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.
- 2Optional
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.
- 3
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.
- 4
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.
- Optional
A 14 px progress ring used as a leading element. It is an image named by its percentage, with an optional extra word.
- Optional
An 8 px coloured dot used as a leading element. Decorative, so say the meaning in the label.
- 5data-slot="sidebar-group"Optional
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.
- Optional
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.
- Optional
A 44 px caption above a run of rows. Hidden in the rail.
- Optional
Placeholder rows while navigation loads. A status region announces Loading navigation, and the rows are hidden from screen readers.
- Optional
A row with a label and a switch, such as Dark mode. The switch hides in the rail.
- Optional
A button row with an avatar, a title, a time and an unread dot. In the rail only the avatar shows.
- 6Optional
A block under the rows with a top border, for the person, workspace or a usage card. It does not scroll with the rows.
- Optional
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.
- Optional
A button with an avatar, a name, a description and a chevron, for switching workspace or account.
- Optional
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.
- data-slot="sidebar-cta"Optional
A full-width primary button for one call to action, such as Upgrade plan. Hidden in the rail.
- 7Optional
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.
- data-slot="sidebar-section-group"Optional
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.
- Optional
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.
- data-slot="sidebar-search"
- data-slot="sidebar-filter"Optional
A filter field for a long list, with a clear button, and Escape clears it. Hidden in the rail.
- data-slot="sidebar-empty"Optional
A status line for a filtered list with no match.
- data-slot="sidebar-resize"
- data-slot="double-sidebar"Optional
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.
- Optional
- Optional
Best practices
- 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.
- Do
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.
- Do
Name every section with an aria-label, and the sidebar itself when the page has more than one aside.
- Do
Give group pages no icons. A group indents its pages under its own label and lists them in a flyout in the rail.
- Do
Keep one level of nesting where you can. A group inside a group is only for a section that really has sub-sections.
- Do
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.
- Do
In the footer, show the person or the workspace, not both. Pick the one the reader switches more often.
- 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
Don't put a logo in the sidebar and in the top bar of the same screen. One logo per screen.
- Don’t
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.
- Do
Let people widen the sidebar with resizable (and widthStorageKey to remember it) instead of a hand-built handle; keep the limits 224 to 384.
API reference
The Sidebar parts are plain components, so the tables list every prop. Rows take the props of a link and the sidebar those of an aside, and SidebarFlyoutContent also takes Popover props.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| logo | ReactNode | — | The logo row at the start. In the rail pass a mark: a wordmark does not fit 48 px. |
| header | ReactNode | — | Replaces with a full-width row, for example a logo with actions. |
| footer | ReactNode | — | A block pinned under the rows with a top border: the person, the workspace, a usage card. |
| rail | ReactNode | — | A 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. |
| collapsed | boolean | false | The 48 px icon rail. Labels stay in the accessibility tree. |
| variant | "docked" | "inset" | "floating" | "docked" | (default), or . |
| tone | "default" | "inverse" | "default" | , or for a dark navigation on a light page. |
| side | "left" | "right" | "left" | (default) or . A docked sidebar draws its rule on the content side. |
| 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. |
| children required | ReactNode | — | , , and the other blocks. They scroll inside the sidebar. |
| defaultWidth | number | 256 | Starting width of a resizable sidebar (and the reset width). Default 256. |
| maxWidth | number | 384 | Default 384. |
| minWidth | number | 224 | Default 224. |
| onWidthChange | (width) => void | — | Each new width while dragging or with the keys. |
| 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 . |
| width | number | — | Controlled width in px of a resizable sidebar. |
| widthStorageKey | string | — | Remembers the width in localStorage under this key. |
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.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| icon | ReactNode | — | A 18 px icon. Required for a top-level row: it is all the rail shows. |
| label required | ReactNode | — | The text of the row. It stays in the accessibility tree in the rail. |
| active | boolean | — | The 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" | (default), , , or . |
| status | "warning" | "error" | "success" | "info" | "neutral" | — | A 6 px dot at the end: , , , or . |
| 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. |
| leading | ReactNode | — | Replaces the icon: a dot, a progress ring, an avatar. |
| action | ReactNode | — | A node shown on hover and focus, usually an icon button that opens a menu. A sibling of the link. |
| trailing | ReactNode | — | Any node at the end of the row. Hidden in the rail. |
| tooltip | boolean | true | Shows the label as a tooltip in the rail. by default. |
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| icon | ReactNode | — | A 18 px icon, the only part of the group the rail shows. |
| label required | 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. |
| defaultOpen | boolean | — | Starts open when uncontrolled. |
| open | boolean | — | Controls the open state. |
| onOpenChange | (open) => void | — | Called with the new open state. |
| guide | boolean | — | Draws a line along the pages. Nested groups inherit it unless they set their own. |
| railFlyout | boolean | true | Shows the flyout of pages in the rail. by default; hides the group so you can render your own. |
| children required | ReactNode | — | pages without icons. |
| ariaLabel | string | — | The accessible name of the rail button when it needs more than the label. |
| 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. by default. |
| leading | ReactNode | — | Replaces the icon. |
| 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. by default. |
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| onToggle | () => void | — | Called when the handle is pressed. Fold the sidebar here. |
| label | string | "Toggle sidebar" | The accessible name of the handle. by default. |
| tabIndex | number | — | The tab order of the handle. by default; takes it out of the tab order when another control folds the sidebar. |
A 44 px caption above a run of rows. Hidden in the rail.
| Prop | Type | Default | Description |
|---|---|---|---|
| children required | ReactNode | — | The caption text. |
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| label required | ReactNode | — | The heading of the section. |
| collapsible | boolean | false | Makes the heading a button that opens and closes the rows. Off by default; always open in the rail. |
| action | ReactNode | — | A node at the end of the heading, such as a New project button. |
| defaultOpen | boolean | — | Starts open when uncontrolled and collapsible. |
| children required | ReactNode | — | The rows, each wrapped in a list item. |
| onOpenChange | (open) => void | — | Called with the new open state. |
| open | boolean | — | Controls the open state. |
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.
| 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, by default. Off a Mac it reads . Display only. |
A filter field for a long list, with a clear button, and Escape clears it. Hidden in the rail.
| Prop | Type | Default | Description |
|---|---|---|---|
| value required | string | — | The text in the field. |
| onValueChange required | (value) => void | — | Called with the new text. Escape and the clear button call it with an empty string. |
| placeholder | string | "Filter…" | The placeholder. by default. |
| label | string | — | The accessible name. Defaults to the placeholder without the ellipsis. |
A status line for a filtered list with no match.
| Prop | Type | Default | Description |
|---|---|---|---|
| children required | ReactNode | — | The sentence to show, for example |
Placeholder rows while navigation loads. A status region announces Loading navigation, and the rows are hidden from screen readers.
| Prop | Type | Default | Description |
|---|---|---|---|
| count | number | 5 | The number of placeholder rows. Five by default. |
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| avatar | ReactNode | — | The avatar at the start. The only part the rail shows. |
| name required | string | — | The person's name. It is the accessible name of the button. |
| 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. |
A button with an avatar, a name, a description and a chevron, for switching workspace or account.
| Prop | Type | Default | Description |
|---|---|---|---|
| avatar required | ReactNode | — | The avatar or logo of the workspace. |
| name required | ReactNode | — | The workspace name. |
| description | ReactNode | — | A second line, such as the number of members. |
| onClick | () => void | — | Called when the row is pressed, usually to open a switcher. |
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| title required | string | — | The name of the quota, and the label of the progress bar. |
| description | string | — | A short value at the end of the title line, such as . |
| value required | number | — | The amount used, from 0 to . |
| max | number | 100 | The limit. by default. |
| tone | "default" | "warning" | "error" | "default" | , or : the title and the bar turn amber or red. |
| 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 . |
| headerTone | "warning" | "error" | "success" | "info" | "purple" | "primary" | "neutral" | "neutral" | The tint of the band. by default. |
| striped | boolean | false | Fills the bar with static diagonal stripes. |
| ariaLabel | string | — | The accessible name of the bar when the title is not enough. |
A full-width primary button for one call to action, such as Upgrade plan. Hidden in the rail.
A row with a label and a switch, such as Dark mode. The switch hides in the rail.
| Prop | Type | Default | Description |
|---|---|---|---|
| checked required | boolean | — | Whether the switch is on. |
| label required | ReactNode | — | The text of the row. |
| onCheckedChange required | (checked) => void | — | Called with the new value. |
| icon | ReactNode | — | An icon at the start. Shown in the rail. |
A button row with an avatar, a title, a time and an unread dot. In the rail only the avatar shows.
| Prop | Type | Default | Description |
|---|---|---|---|
| avatar required | ReactNode | — | The avatar at the start. The only part the rail shows. |
| title required | ReactNode | — | What happened, one line. |
| onClick | () => void | — | Called when the row is pressed. |
| time | ReactNode | — | When, in tertiary text. |
| unread | boolean | — | Shows the unread dot. |
A 14 px progress ring used as a leading element. It is an image named by its percentage, with an optional extra word.
| Prop | Type | Default | Description |
|---|---|---|---|
| value required | number | — | The progress, 0 to 100. It is in the accessible name. |
| label | string | — | A word added to the accessible name, such as . |
| size | number | 14 | The diameter in px. 14 by default. |
| tone | "warning" | "error" | "success" | "info" | "default" | "purple" | "default" | , , , , or . |
An 8 px coloured dot used as a leading element. Decorative, so say the meaning in the label.
| Prop | Type | Default | Description |
|---|---|---|---|
| tone required | "warning" | "error" | "success" | "info" | "purple" | "pink" | "orange" | "primary" | — | The colour of the dot: , , , , , , or . |
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| align | "center" | "end" | "start" | "center" | How the flyout lines up with the trigger: , or . in a group. |
| anchor | Element | null | VirtualElement | RefObject<Element | null> | () => unknown | — | Another element to anchor to instead of the trigger. |
| finalFocus | boolean | RefObject<HTMLElement | null> | (closeType) => unknown | — | Which element takes focus when it closes. |
| initialFocus | boolean | RefObject<HTMLElement | null> | (openType) => unknown | — | Which element takes focus when the flyout opens. |
| 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. |
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| children required | ReactNode | — | The sidebar of the pages of one area. |
| rail | ReactNode | — | The collapsed sidebar of the areas. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("sidebar")The full library index for assistants is at /llms.txt.