Sidebar

一个可组合、可主题化且可定制的侧边栏组件。

侧边栏是最复杂的组件之一。它们是任何应用的核心，通常包含许多相互关联的部分。

现在我们已经有了一个扎实的基础可以在其上继续构建。可组合。可主题化。可定制。

安装


pnpm dlx shadcn@latest add sidebar

结构

Sidebar 组件由以下部分组成：

SidebarProvider - 处理可折叠状态。
Sidebar - 侧边栏容器。
SidebarHeader 和 SidebarFooter - 固定在侧边栏顶部和底部。
SidebarContent - 可滚动内容。
SidebarGroup - SidebarContent 内的分区。
SidebarTrigger - Sidebar 的触发器。

用法

app/layout.tsx

import { SidebarProvider, SidebarTrigger } from "@/components/ui/sidebar"
import { AppSidebar } from "@/components/app-sidebar"
 
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <SidebarProvider>
      <AppSidebar />
      <main>
        <SidebarTrigger />
        {children}
      </main>
    </SidebarProvider>
  )
}

components/app-sidebar.tsx

import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarHeader,
} from "@/components/ui/sidebar"
 
export function AppSidebar() {
  return (
    <Sidebar>
      <SidebarHeader />
      <SidebarContent>
        <SidebarGroup />
        <SidebarGroup />
      </SidebarContent>
      <SidebarFooter />
    </Sidebar>
  )
}

SidebarProvider

SidebarProvider 组件用于为 Sidebar 组件提供侧边栏上下文。你应该始终用 SidebarProvider 组件包裹应用。

属性

名称	类型	描述
`defaultOpen`	`boolean`	侧边栏的默认展开状态。
`open`	`boolean`	侧边栏的展开状态（受控）。
`onOpenChange`	`(open: boolean) => void`	设置侧边栏的展开状态（受控）。

宽度

如果你的应用只有一个侧边栏，可以在 sidebar.tsx 中使用 SIDEBAR_WIDTH 和 SIDEBAR_WIDTH_MOBILE 变量来设置侧边栏宽度。

components/ui/sidebar.tsx

const SIDEBAR_WIDTH = "16rem"
const SIDEBAR_WIDTH_MOBILE = "18rem"

如果你的应用中有多个侧边栏，可以在 style 属性中使用 --sidebar-width 和 --sidebar-width-mobile CSS 变量。

<SidebarProvider
  style={
    {
      "--sidebar-width": "20rem",
      "--sidebar-width-mobile": "20rem",
    } as React.CSSProperties
  }
>
  <Sidebar />
</SidebarProvider>

键盘快捷键

要触发侧边栏，在 Mac 上使用 cmd+b 快捷键，在 Windows 上使用 ctrl+b。

components/ui/sidebar.tsx

const SIDEBAR_KEYBOARD_SHORTCUT = "b"

Sidebar

用于渲染可折叠侧边栏的主 Sidebar 组件。

属性

属性	类型	描述
`side`	`left` or `right`	侧边栏所在的一侧。
`variant`	`sidebar`, `floating`, or `inset`	侧边栏的变体。
`collapsible`	`offcanvas`, `icon`, or `none`	侧边栏的可折叠状态。

Prop	Description
`offcanvas`	从左侧或右侧滑入的可折叠侧边栏。
`icon`	折叠为图标的侧边栏。
`none`	不可折叠的侧边栏。

注意： 如果你使用 inset 变体，请记得将主内容包裹在 SidebarInset 组件中。

<SidebarProvider>
  <Sidebar variant="inset" />
  <SidebarInset>
    <main>{children}</main>
  </SidebarInset>
</SidebarProvider>

useSidebar

useSidebar hook 用于控制侧边栏。

import { useSidebar } from "@/components/ui/sidebar"
 
export function AppSidebar() {
  const {
    state,
    open,
    setOpen,
    openMobile,
    setOpenMobile,
    isMobile,
    toggleSidebar,
  } = useSidebar()
}

属性	类型	描述
`state`	`expanded` or `collapsed`	侧边栏当前状态。
`open`	`boolean`	侧边栏是否展开。
`setOpen`	`(open: boolean) => void`	设置侧边栏展开状态。
`openMobile`	`boolean`	侧边栏在移动端是否展开。
`setOpenMobile`	`(open: boolean) => void`	设置侧边栏在移动端的展开状态。
`isMobile`	`boolean`	侧边栏是否处于移动端。
`toggleSidebar`	`() => void`	切换侧边栏。适用于桌面端和移动端。

SidebarHeader

使用 SidebarHeader 组件为侧边栏添加一个固定头部。

components/app-sidebar.tsx

<Sidebar>
  <SidebarHeader>
    <SidebarMenu>
      <SidebarMenuItem>
        <DropdownMenu>
          <DropdownMenuTrigger asChild>
            <SidebarMenuButton>
              Select Workspace
              <ChevronDown className="ml-auto" />
            </SidebarMenuButton>
          </DropdownMenuTrigger>
          <DropdownMenuContent className="w-[--radix-popper-anchor-width]">
            <DropdownMenuItem>
              <span>Acme Inc</span>
            </DropdownMenuItem>
          </DropdownMenuContent>
        </DropdownMenu>
      </SidebarMenuItem>
    </SidebarMenu>
  </SidebarHeader>
</Sidebar>

SidebarFooter

使用 SidebarFooter 组件为侧边栏添加一个固定页脚。

<Sidebar>
  <SidebarFooter>
    <SidebarMenu>
      <SidebarMenuItem>
        <SidebarMenuButton>
          <User2 /> Username
        </SidebarMenuButton>
      </SidebarMenuItem>
    </SidebarMenu>
  </SidebarFooter>
</Sidebar>

SidebarContent

SidebarContent 组件用于包裹侧边栏内容。你应在这里添加 SidebarGroup 组件。它是可滚动的。

<Sidebar>
  <SidebarContent>
    <SidebarGroup />
    <SidebarGroup />
  </SidebarContent>
</Sidebar>

SidebarGroup

使用 SidebarGroup 组件在侧边栏中创建一个分区。

A SidebarGroup has a SidebarGroupLabel, a SidebarGroupContent and an optional SidebarGroupAction.

<SidebarGroup>
  <SidebarGroupLabel>Application</SidebarGroupLabel>
  <SidebarGroupAction>
    <Plus /> <span className="sr-only">Add Project</span>
  </SidebarGroupAction>
  <SidebarGroupContent></SidebarGroupContent>
</SidebarGroup>

To make a SidebarGroup collapsible, wrap it in a Collapsible.

<Collapsible defaultOpen className="group/collapsible">
  <SidebarGroup>
    <SidebarGroupLabel asChild>
      <CollapsibleTrigger>
        Help
        <ChevronDown className="ml-auto transition-transform group-data-[state=open]/collapsible:rotate-180" />
      </CollapsibleTrigger>
    </SidebarGroupLabel>
    <CollapsibleContent>
      <SidebarGroupContent />
    </CollapsibleContent>
  </SidebarGroup>
</Collapsible>

SidebarMenu

SidebarMenu 组件用于在 SidebarGroup 内构建菜单。

<SidebarMenu>
  {projects.map((project) => (
    <SidebarMenuItem key={project.name}>
      <SidebarMenuButton asChild>
        <a href={project.url}>
          <project.icon />
          <span>{project.name}</span>
        </a>
      </SidebarMenuButton>
    </SidebarMenuItem>
  ))}
</SidebarMenu>

SidebarMenuButton

SidebarMenuButton 组件用于在 SidebarMenuItem 内渲染菜单按钮。

默认情况下，SidebarMenuButton 会渲染一个按钮，但你可以使用 asChild 属性来渲染其他组件，例如 Link 或 a 标签。

使用 isActive 属性将菜单项标记为激活状态。

<SidebarMenuButton asChild isActive>
  <a href="#">Home</a>
</SidebarMenuButton>

SidebarMenuAction

SidebarMenuAction 组件用于在 SidebarMenuItem 内渲染菜单操作。

<SidebarMenuItem>
  <SidebarMenuButton asChild>
    <a href="#">
      <Home />
      <span>Home</span>
    </a>
  </SidebarMenuButton>
  <SidebarMenuAction>
    <Plus /> <span className="sr-only">Add Project</span>
  </SidebarMenuAction>
</SidebarMenuItem>

SidebarMenuSub

SidebarMenuSub 组件用于在 SidebarMenu 内渲染子菜单。

<SidebarMenuItem>
  <SidebarMenuButton />
  <SidebarMenuSub>
    <SidebarMenuSubItem>
      <SidebarMenuSubButton />
    </SidebarMenuSubItem>
  </SidebarMenuSub>
</SidebarMenuItem>

SidebarMenuBadge

SidebarMenuBadge 组件用于在 SidebarMenuItem 内渲染徽标。

<SidebarMenuItem>
  <SidebarMenuButton />
  <SidebarMenuBadge>24</SidebarMenuBadge>
</SidebarMenuItem>

SidebarMenuSkeleton

SidebarMenuSkeleton 组件用于为 SidebarMenu 渲染骨架屏。

<SidebarMenu>
  {Array.from({ length: 5 }).map((_, index) => (
    <SidebarMenuItem key={index}>
      <SidebarMenuSkeleton />
    </SidebarMenuItem>
  ))}
</SidebarMenu>

SidebarTrigger

使用 SidebarTrigger 组件渲染一个用于切换侧边栏的按钮。

import { useSidebar } from "@/components/ui/sidebar"
 
export function CustomTrigger() {
  const { toggleSidebar } = useSidebar()
 
  return <button onClick={toggleSidebar}>Toggle Sidebar</button>
}

SidebarRail

SidebarRail 组件用于在 Sidebar 内渲染一个轨道。这个轨道可用于切换侧边栏。

<Sidebar>
  <SidebarHeader />
  <SidebarContent>
    <SidebarGroup />
  </SidebarContent>
  <SidebarFooter />
  <SidebarRail />
</Sidebar>

受控侧边栏

使用 open 和 onOpenChange 属性来控制侧边栏。

export function AppSidebar() {
  const [open, setOpen] = React.useState(false)
 
  return (
    <SidebarProvider open={open} onOpenChange={setOpen}>
      <Sidebar />
    </SidebarProvider>
  )
}

主题

我们使用以下 CSS 变量为侧边栏设置主题。

@layer base {
  :root {
    --sidebar-background: 0 0% 98%;
    --sidebar-foreground: 240 5.3% 26.1%;
    --sidebar-primary: 240 5.9% 10%;
    --sidebar-primary-foreground: 0 0% 98%;
    --sidebar-accent: 240 4.8% 95.9%;
    --sidebar-accent-foreground: 240 5.9% 10%;
    --sidebar-border: 220 13% 91%;
    --sidebar-ring: 217.2 91.2% 59.8%;
  }
 
  .dark {
    --sidebar-background: 240 5.9% 10%;
    --sidebar-foreground: 240 4.8% 95.9%;
    --sidebar-primary: 0 0% 98%;
    --sidebar-primary-foreground: 240 5.9% 10%;
    --sidebar-accent: 240 3.7% 15.9%;
    --sidebar-accent-foreground: 240 4.8% 95.9%;
    --sidebar-border: 240 3.7% 15.9%;
    --sidebar-ring: 217.2 91.2% 59.8%;
  }
}

样式

以下是根据不同状态为侧边栏设置样式的一些建议。

<Sidebar collapsible="icon">
  <SidebarContent>
    <SidebarGroup className="group-data-[collapsible=icon]:hidden" />
  </SidebarContent>
</Sidebar>

<SidebarMenuItem>
  <SidebarMenuButton />
  <SidebarMenuAction className="peer-data-[active=true]/menu-button:opacity-100" />
</SidebarMenuItem>

RTL

要在 shadcn/ui 中启用 RTL 支持，请参见 RTL 配置指南。

查看 RTL 侧边栏

更新日志

RTL 支持

如果你正在从旧版本的 Sidebar 组件升级，则需要应用以下更新来添加 RTL 支持：

为 Sidebar 组件添加 `dir` 属性。

Add dir to the destructured props and pass it to SheetContent for mobile:

  function Sidebar({
    side = "left",
    variant = "sidebar",
    collapsible = "offcanvas",
    className,
    children,
+   dir,
    ...props
  }: React.ComponentProps<"div"> & {
    side?: "left" | "right"
    variant?: "sidebar" | "floating" | "inset"
    collapsible?: "offcanvas" | "icon" | "none"
  }) {

Then pass it to SheetContent in the mobile view:

  <Sheet open={openMobile} onOpenChange={setOpenMobile} {...props}>
    <SheetContent
+     dir={dir}
      data-sidebar="sidebar"
      data-slot="sidebar"
      data-mobile="true"

为侧边栏容器添加 `data-side` 属性。

Add data-side={side} to the sidebar container element:

  <div
    data-slot="sidebar-container"
+   data-side={side}
    className={cn(

更新侧边栏容器的定位类。

Replace JavaScript ternary conditional classes with CSS data attribute selectors:

  className={cn(
-   "fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear md:flex",
-   side === "left"
-     ? "left-0 group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)]"
-     : "right-0 group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)]",
+   "fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear md:flex data-[side=left]:left-0 data-[side=right]:right-0 data-[side=left]:group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)] data-[side=right]:group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)]",

更新 SidebarRail 的定位类。

Update the SidebarRail component to use physical positioning for the rail:

  className={cn(
-   "hover:after:bg-sidebar-border absolute inset-y-0 z-20 hidden w-4 -translate-x-1/2 transition-all ease-linear group-data-[side=left]:-end-4 group-data-[side=right]:start-0 after:absolute after:inset-y-0 after:start-1/2 after:w-[2px] sm:flex",
+   "hover:after:bg-sidebar-border absolute inset-y-0 z-20 hidden w-4 ltr:-translate-x-1/2 rtl:-translate-x-1/2 transition-all ease-linear group-data-[side=left]:-right-4 group-data-[side=right]:left-0 after:absolute after:inset-y-0 after:start-1/2 after:w-[2px] sm:flex",

为 SidebarTrigger 图标添加 RTL 翻转。

Add className="rtl:rotate-180" to the icon in SidebarTrigger to flip it in RTL mode:

  <Button ...>
-   <PanelLeftIcon />
+   <PanelLeftIcon className="rtl:rotate-180" />
    <span className="sr-only">Toggle Sidebar</span>
  </Button>

After applying these changes, you can use the dir prop to set the direction:

<Sidebar dir="rtl" side="right">
  {/* ... */}
</Sidebar>

侧边栏将能够在 LTR 和 RTL 布局中正确定位并处理交互。

Sheet Skeleton

用 Dory 探索你的数据

AI 驱动的 SQL 工作台，连接 Postgres / MySQL 等数据库，快速查询与分析数据。

用 AI 快速得到答案，开源且免费。

Sidebar

安装

结构

用法

SidebarProvider

属性

宽度

键盘快捷键

Sidebar

属性

useSidebar

SidebarHeader

SidebarFooter

SidebarContent

SidebarGroup

SidebarMenu

SidebarMenuButton

SidebarMenuAction

SidebarMenuSub

SidebarMenuBadge

SidebarMenuSkeleton

SidebarTrigger

SidebarRail

受控侧边栏

主题

样式

RTL

更新日志

RTL 支持

为 Sidebar 组件添加 dir 属性。

为侧边栏容器添加 data-side 属性。

更新侧边栏容器的定位类。

更新 SidebarRail 的定位类。

为 SidebarTrigger 图标添加 RTL 翻转。

为 Sidebar 组件添加 `dir` 属性。

为侧边栏容器添加 `data-side` 属性。