- 手风琴
- 提示
- 警告对话框
- 宽高比
- 头像
- 徽章
- 面包屑导航
- 按钮
- 按钮组
- 日历 Calendar
- 卡片
- Carousel
- 图表 Chart
- 复选框
- 折叠面板
- 组合框
- 命令
- 上下文菜单
- 数据表格 Data Table
- 日期选择器 Date Picker
- 对话框 Dialog
- 方向
- 抽屉
- 下拉菜单
- Empty
- 字段
- 悬停卡片
- 输入
- 输入组
- 输入 OTP
- 项目
- Kbd
- 标签
- 菜单栏
- 原生选择框
- 导航菜单 Navigation Menu
- 分页
- 弹出框
- 进度 Progress
- 单选框组
- 可调整大小
- 滚动区域 Scroll Area
- 选择框
- 分隔符 Separator
- 侧边栏 Sheet
- 侧边栏 Sidebar
- 骨架屏
- 滑块
- Sonner
- 加载指示器 Spinner
- 开关
- 表格
- 标签页 Tabs
- 文本域
- 吐司
- 切换按钮 Toggle
- 切换组
- 提示 Tooltip
- 排版


一个可折叠为图标的侧边栏。
侧边栏是最复杂的组件之一。它们是任何应用程序的核心,并且通常包含许多动态部分。
现在我们有了一个坚实的基础。可组合。可主题。可定制。
安装
pnpm dlx shadcn@latest add sidebar
结构
一个 Sidebar 组件由以下部分组成:
SidebarProvider- 处理可折叠状态。Sidebar- 侧边栏容器。SidebarHeader和SidebarFooter- 分别固定在侧边栏的顶部和底部。SidebarContent- 可滚动内容区域。SidebarGroup- 侧边栏内容内的分组区域。SidebarTrigger- 侧边栏的触发按钮。
用法
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>
)
}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 变量来设置侧边栏宽度。
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。
const SIDEBAR_KEYBOARD_SHORTCUT = "b"Sidebar
主要的 Sidebar 组件用于渲染一个可折叠的侧边栏。
属性
| 属性 | 类型 | 说明 |
|---|---|---|
side | 'left' 或 'right' | 侧边栏出现的侧边。 |
variant | 'sidebar'、'floating' 或 'inset' | 侧边栏的样式变体。 |
collapsible | 'offcanvas'、'icon' 或 'none' | 侧边栏的可折叠状态。 |
| Prop | Description |
|---|---|
offcanvas | 可折叠的侧边栏,从左或右侧滑入。 |
icon | 可折叠为图标的侧边栏。 |
none | 不可折叠的侧边栏。 |
注意: 如果使用 inset 变体,记得用 SidebarInset 组件包裹主内容。
<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()
}| 属性 | 类型 | 说明 |
|---|---|---|
state | 'expanded' 或 'collapsed' | 当前侧边栏状态。 |
open | boolean | 侧边栏是否打开。 |
setOpen | (open: boolean) => void | 设置侧边栏打开状态。 |
openMobile | boolean | 移动端侧边栏是否打开。 |
setOpenMobile | (open: boolean) => void | 设置移动端侧边栏打开状态。 |
isMobile | boolean | 是否处于移动端状态。 |
toggleSidebar | () => void | 切换侧边栏开关。支持桌面和移动端。 |
SidebarHeader
使用 SidebarHeader 组件添加侧边栏的固定头部。
<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 创建侧边栏的分区。
SidebarGroup 包含一个 SidebarGroupLabel、一个 SidebarGroupContent 和一个可选的 SidebarGroupAction。
<SidebarGroup>
<SidebarGroupLabel>Application</SidebarGroupLabel>
<SidebarGroupAction>
<Plus /> <span className="sr-only">Add Project</span>
</SidebarGroupAction>
<SidebarGroupContent></SidebarGroupContent>
</SidebarGroup>要使 SidebarGroup 可折叠,可将其包裹在 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="#">首页</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>
<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 属性。
在解构 props 中添加 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 data 属性选择器替换 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">Toggle Sidebar</span>
</Button>应用这些更改后,可以使用 dir 属性设置方向:
<Sidebar dir="rtl" side="right">
{/* ... */}
</Sidebar>侧边栏将在 LTR 和 RTL 布局中正确定位并处理交互。