组件

Sidebar

An order pad hung from the top of the screen: cream paper with a torn top edge and a binder clip. Rows carry their own line of the pad's ruling, hover is the highlighter, and the current page is marked with a highlighter swipe and a bracket in the margin. It collapses to icons or slides away, becomes a sheet on phones, and stays cheap for a long menu: only the one active row draws anything.

安装

terminal
npx shadcn@latest add @wobko/sidebar

第一次使用?先把 registry 加进 components.json。 如何安装

示例

App sidebar

The real thing: a team switcher in the header, a group with a collapsible sub-menu, projects with per-row actions and a count, and the account menu in the footer. The current page has the highlighter and the bracket in the margin. Try Ctrl/Cmd+B.

Collapse to icons

collapsible="icon" shrinks the pad to a 3rem strip: labels fade, the margin bracket steps aside, the binder clip comes off, and each button names itself in a tooltip. The state is controlled here so the page can read it.

Variants and sides

sidebar docks to the edge and casts its shadow toward the page; floating is set down on the desk and turned a little; inset leaves a margin and makes the page itself a sheet of paper. Either side of the screen works, and the clip and torn edge follow.

Search and loading

A long menu stays cheap: 40 notebooks are 40 list items with no drawing each, only the current one draws its mark. The search field filters them, the plus on the label adds one, and Reload shows loading rows (their widths come from a seed, so they are the same on the server and the client).

Demo

Official `sidebar-demo`: one group of five links and an inset with the trigger. The pad hangs from a binder clip and every link wears the highlighter when pointed at. The outer frame is only there so the fixed pad stays inside this preview (in an app the provider goes at the root); try Ctrl/Cmd+B.

Header and footer

Official `sidebar-header` and `sidebar-footer` in one pad: a workspace switcher on top whose menu opens downward at the width of its button, and an account menu at the bottom that opens upward (`side="top"`). While a menu is open its button keeps the highlighter, where shadcn tints it with the accent color.

Group

Official `sidebar-group`: a `SidebarGroup` is a label (a typewriter kicker) over a menu. Two buttons here; a pad can hold as many groups as it likes. Like the original, this one has no inset page beside it.

Collapsible group

Official `sidebar-group-collapsible`: the group label becomes the trigger of a Collapsible (`SidebarGroupLabel asChild` around `CollapsibleTrigger`), with a chevron that turns over as it opens. The label wears the highlighter on hover, where shadcn tints it with the accent color.

Group action

Official `sidebar-group-action`: a `SidebarGroupAction` is a small button in the corner of a group, next to its label. Here the plus posts a toast. The original parks the Toaster at the bottom left with a margin to clear the sidebar; inside this frame it sits at the bottom right instead.

Menu

Official `sidebar-menu`: five projects as `SidebarMenuButton asChild` around links. Each row carries its own line of the pad's ruling, painted by CSS, so this list costs no drawing per row; only a current page (`isActive`) draws a mark.

Menu action and badge

Official `sidebar-menu-action` and `sidebar-menu-badge` in one pad. Top group: each row has a `SidebarMenuAction` (a small button that opens a menu), and the row keeps the highlighter while its menu is open. Bottom group: a `SidebarMenuBadge` writes a count in the margin in blue felt tip. Action and badge share the same corner, so a row takes one or the other.

Menu sub

Official `sidebar-menu-sub`: a table of contents, each section a button over an indented `SidebarMenuSub` that is always open. A pencil line runs down the start of each sub-list. The content scrolls inside the pad when it is taller than the pad. The data is the original's, written as strings.

Menu collapsible

Official `sidebar-menu-collapsible`: the same table of contents with each section folding open and shut. The first section starts open. The original wraps each item in a `div`, which is not valid inside a `ul`; `Collapsible asChild` here lets the `li` itself be the collapsible, so the list markup stays valid and the chevron still turns from `group-data-[state=open]/collapsible`.

Controlled and loading

Official `sidebar-controlled` and `sidebar-rsc` in one pad. Controlled: `open` and `onOpenChange` on the provider, with the state kept in the page so any button can open and close the pad. Loading: `SidebarMenuSkeleton` rows (with icons) stand in while the projects load, then are swapped for the list. The original's loading is a React Server Component behind Suspense, which a client-only page cannot show, so a timer stands in for the fetch. Reload runs it again.

API 参考

SidebarProvider

Holds the open state (cookie `sidebar_state`, 7 days), the Ctrl/Cmd+B shortcut, the phone sheet's state and a TooltipProvider. Set the widths with `--sidebar-width` and `--sidebar-width-icon` in `style`.

属性类型默认值说明
defaultOpenbooleantrueInitial state when uncontrolled. Read the cookie on the server to restore it.
open / onOpenChangeboolean / (open: boolean) => void-Controlled state.

Sidebar

The pad. Desktop: a fixed container beside a gap that reserves its width, holding the pad (a Paper: order-pad stock, torn top edge drawn, binder clip). Phone: the same pad in a Sheet. `className` and props go to the fixed container, as upstream.

属性类型默认值说明
side"left" | "right""left"Which edge it hangs on.
variant"sidebar" | "floating" | "inset""sidebar"`sidebar` docks to the edge and casts its shadow toward the page; `floating` is set down on the desk a little turned; `inset` leaves room around the pad and turns SidebarInset into a sheet of paper.
collapsible"offcanvas" | "icon" | "none""offcanvas"Slide away, shrink to icons (3rem, labels fade, the margin bracket hides), or never collapse.
stockStockName"pad"What the pad is made of. A stock with a cut edge (`paper`, `kraft`...) is a pure CSS sheet.
clipbooleantrue (false with collapsible="none")The binder clip at the top. A docked pad hangs it in the gutter above the torn edge; the phone sheet and a `collapsible="none"` pad have no gutter, so the clip stands on the paper and the pad's top padding grows to clear it (`collapsible="none"` is opt-in, since a static pad sits wherever you put it). Never drawn in calm density or when collapsed to icons.
seedstring | number-Pins the hand: the same seed always tears and clips the pad the same way.

SidebarGroupLabel

The section's heading, in the typewriter. It fades and closes up when collapsed to icons.

属性类型默认值说明
asChildbooleanfalseRender your element (a Collapsible trigger, say).

SidebarGroupAction

A small button at the end of the group's label row.

属性类型默认值说明
asChildbooleanfalseRender your element.

SidebarMenuButton

The row's button, or your link with `asChild`. Not an ink host: hover and keyboard focus wear the highlighter as a CSS background, and a CSS gradient under it is the row's line of the pad's ruling (so the lines always meet the rows; hidden when collapsed to icons and in calm density). The current page (`isActive`) mounts one small drawing inside it, a highlighter swipe with a bracket in the margin; the `outline` variant draws a pencil box the same way.

属性类型默认值说明
isActivebooleanfalseMarks the current page: bold, highlighter, margin bracket, `data-active`. With `asChild` the link gets `aria-current="page"` too.
variant"default" | "outline""default"`outline` adds a pencil box.
size"default" | "sm" | "lg""default"32, 28 or 48 px high.
tooltipstring | TooltipContent props-Names the row when the sidebar is collapsed to icons (never shown when expanded or on phones).
asChildbooleanfalseRender your link instead of a button; the mark lands inside it.

SidebarMenuAction

A small button at the end of a row.

属性类型默认值说明
showOnHoverbooleanfalseOnly visible on hover or focus within the row (always visible on touch).
asChildbooleanfalseRender your element (a DropdownMenuTrigger).

SidebarMenuSkeleton

A loading row of pencil hatch. Its width is derived from the seed (50 to 90 %), not from a random number, so the server and the client agree.

属性类型默认值说明
showIconbooleanfalseA square for the icon.
seedstring | number-Pins the width. Default: from useId().

SidebarMenuSubButton

The sub-row's link (`a`), or your element with `asChild`. The current one is bold on the highlighter. 28 px high for one line; a title that wraps makes its row taller instead of running over the next one (a trailing `span` still truncates).

属性类型默认值说明
isActivebooleanfalseMarks the current page.
size"sm" | "md""md"15 or 16 px text.
asChildbooleanfalseRender your link.

无障碍

  • The sidebar adds no landmark of its own: wrap it in a `nav` (or give it `aria-label` on the Sidebar's container) so screen readers can find it. The rows are ordinary buttons and links in a list; `isActive` on a link (`asChild`) or a sub-menu button sets `aria-current="page"` for you (pass your own to override; a plain button gets none); the drawing is decoration.
  • Ctrl or Cmd + B toggles it from anywhere; the SidebarTrigger is a labeled button ("Toggle Sidebar"). The rail is not a tab stop. On phones the pad opens in a Sheet: a dialog named "Sidebar" that traps focus, closes with Escape or a tap on the scrim and gives focus back to whatever opened it (Radix only does that for its own Trigger, so the Sidebar remembers the opener itself). Growing the window past the phone width closes the sheet, so it does not come back by itself when the window shrinks again. Ctrl/Cmd+B is left alone when something nearer (a rich-text editor's Bold) has already handled the key.
  • Keyboard focus on a row shows the highlighter and the theme's blue focus ring. Every row is at least 28 px high (32 by default); collapsed rows are 32 px squares, named by their tooltip and their text (keep the label in a `span` so it stays in the accessible name).
  • When it collapses to icons the labels are hidden with CSS only, so the accessible names stay. Tooltips appear on hover and keyboard focus, never on touch.
  • The torn edge, ruled lines, binder clip, bracket and sub-menu line are aria-hidden decoration with no pointer events. In forced-colors mode the clip is hidden and the drawings give way to real outlines. Reduced motion collapses the slide of the pad and the fade of the labels.
  • The open state is remembered in the `sidebar_state` cookie; read it on the server to render the right state on first paint.

源码

CLI 会复制进你项目的文件。

正在加载源码