110k

侧边栏

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

sidebar-demo

一个可折叠为图标的侧边栏。

侧边栏是最复杂的组件之一。它们是任何应用的核心,通常包含许多动态部分。

我们现在拥有了坚实的基础可以在此之上构建。可组合。可主题化。 可自定义。

浏览组件库

安装

pnpm dlx shadcn@latest add sidebar

结构

Sidebar 组件由以下部分组成:

  • SidebarProvider - 处理折叠状态。
  • Sidebar - 侧边栏容器。
  • SidebarHeaderSidebarFooter - 分别位于侧边栏的顶部和底部,且为粘性定位。
  • SidebarContent - 可滚动的内容区域。
  • SidebarGroup - SidebarContent 中的分组区域。
  • SidebarTrigger - 用于触发侧边栏的开关。
侧边栏结构

使用方法

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 组件包裹你的应用。

参数

名称类型描述
defaultOpenboolean侧边栏的默认打开状态。
openboolean侧边栏的打开状态(受控)。
onOpenChange(open: boolean) => void设置侧边栏的打开状态(受控)。

宽度

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

components/ui/sidebar.tsx
const SIDEBAR_WIDTH = "16rem"
const SIDEBAR_WIDTH_MOBILE = "18rem"

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

<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 组件用于渲染可折叠的侧边栏。

参数

属性类型描述
sideleftright侧边栏所在的边。
variantsidebarfloatinginset侧边栏的变体类型。
collapsibleoffcanvasiconnone侧边栏的折叠状态。
属性描述
offcanvas可折叠的侧边栏,会从左侧或右侧滑入。
icon折叠为图标的侧边栏。
none不可折叠的侧边栏。
<SidebarProvider>
  <Sidebar variant="inset" />
  <SidebarInset>
    <main>{children}</main>
  </SidebarInset>
</SidebarProvider>

useSidebar

useSidebar 钩子用于控制侧边栏。

import { useSidebar } from "@/components/ui/sidebar"
 
export function AppSidebar() {
  const {
    state,
    open,
    setOpen,
    openMobile,
    setOpenMobile,
    isMobile,
    toggleSidebar,
  } = useSidebar()
}
属性类型描述
stateexpandedcollapsed侧边栏当前状态。
openboolean侧边栏是否打开。
setOpen(open: boolean) => void设置侧边栏的打开状态。
openMobileboolean移动端侧边栏是否打开。
setOpenMobile(open: boolean) => void设置移动端侧边栏的打开状态。
isMobileboolean是否为移动端侧边栏。
toggleSidebar() => void切换侧边栏。支持桌面端和移动端。

SidebarHeader

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

components/app-sidebar.tsx
<Sidebar>
  <SidebarHeader>
    <SidebarMenu>
      <SidebarMenuItem>
        <DropdownMenu>
          <DropdownMenuTrigger asChild>
            <SidebarMenuButton>
              选择工作区
              <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 /> 用户名
        </SidebarMenuButton>
      </SidebarMenuItem>
    </SidebarMenu>
  </SidebarFooter>
</Sidebar>

SidebarContent

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

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

SidebarGroup

使用 SidebarGroup 组件创建侧边栏内的分组区块。

SidebarGroup 包含一个 SidebarGroupLabel,一个 SidebarGroupContent,以及一个可选的 SidebarGroupAction

<SidebarGroup>
  <SidebarGroupLabel>应用</SidebarGroupLabel>
  <SidebarGroupAction>
    <Plus /> <span className="sr-only">添加项目</span>
  </SidebarGroupAction>
  <SidebarGroupContent></SidebarGroupContent>
</SidebarGroup>

如果你想让 SidebarGroup 可折叠,可以用 Collapsible 组件包裹它。

<Collapsible defaultOpen className="group/collapsible">
  <SidebarGroup>
    <SidebarGroupLabel asChild>
      <CollapsibleTrigger>
        帮助
        <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 属性来渲染为其他组件,比如 Linka 标签。

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

<SidebarMenuButton asChild isActive>
  <a href="#">首页</a>
</SidebarMenuButton>

SidebarMenuAction

SidebarMenuAction 组件用于在 SidebarMenuItem 中渲染操作按钮。

<SidebarMenuItem>
  <SidebarMenuButton asChild>
    <a href="#">
      <Home />
      <span>首页</span>
    </a>
  </SidebarMenuButton>
  <SidebarMenuAction>
    <Plus /> <span className="sr-only">添加项目</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}>切换侧边栏</button>
}

SidebarRail

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

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

受控侧边栏

使用 openonOpenChange 属性来控制侧边栏。

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 属性。

在解构的属性中添加 dir,并传递给移动端的 SheetContent

  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"
  }) {

然后在移动端视图中传递给 SheetContent

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

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

为侧边栏容器元素添加 data-side={side}

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

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

使用 CSS 数据属性选择器替代 JavaScript 三元条件类名:

  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 定位类名。

SidebarRail 组件改为使用物理定位:

  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 翻转。

SidebarTrigger 中的图标添加 className="rtl:rotate-180" 以支持 RTL 模式下翻转:

  <Button ...>
-   <PanelLeftIcon />
+   <PanelLeftIcon className="rtl:rotate-180" />
    <span className="sr-only">切换侧边栏</span>
  </Button>

完成上述改动后,你就可以使用 dir 属性来设置方向:

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

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