🎛️

shadcn-admin

Admin Dashboard UI crafted with Shadcn and Vite. Built with responsiveness and accessibility in mind.

10.9k
Stars
1.8k
Forks
v2.2.1
Latest
MIT
License

GitHub · Live Demo

1. 项目简介

shadcn-admin 是一个基于 Shadcn UI 和 Vite 构建的现代化管理后台模板。该项目专注于响应式设计和无障碍访问，提供了一套完整的 Admin Dashboard 解决方案。

💡
主要用途
适用于需要快速搭建企业级管理后台的开发者，提供开箱即用的 UI 组件和页面模板。

目标用户

  • 需要快速构建 Admin Dashboard 的前端开发者
  • 寻找 Shadcn UI 最佳实践参考的团队
  • 需要响应式、可访问性友好的管理后台模板

2. 核心功能

🌓 主题系统
  • Light/Dark 模式切换
  • 自动跟随系统主题
  • 主题状态持久化
📱 响应式设计
  • 完全响应式布局，适配各种屏幕尺寸
  • 移动端友好的侧边栏和导航
  • 自适应 Data Table 组件
♿ 无障碍访问
  • 基于 Radix UI 的无障碍原语
  • 键盘导航支持
  • 屏幕阅读器友好
  • Skip to main content 功能
🔍 全局搜索
  • Command 菜单式全局搜索
  • 快捷键触发 (⌘K / Ctrl+K)
  • 页面、功能快速跳转
🌍 RTL 支持
  • 完整的从右到左 (RTL) 语言支持
  • 多个组件已针对 RTL 进行优化
  • Direction Provider 全局管理
📊 数据表格
  • 基于 TanStack Table 的高级数据表格
  • 排序、筛选、分页功能
  • 批量操作工具栏
  • 列可见性控制
  • Faceted Filter 多选筛选
🔐 认证系统
  • 集成 Clerk 认证
  • 受保护路由
  • 登录/注册页面
  • 忘记密码/OTP 验证流程

3. 技术栈

类别 技术 版本
UI 框架 Shadcn UI (TailwindCSS + RadixUI) -
样式 TailwindCSS 4.1.18
构建工具 Vite 7.3.0
框架 React 19.2.3
路由 TanStack Router -
状态管理 Zustand -
数据获取 TanStack Query + Axios -
表单 React Hook Form + Zod -
图表 Recharts -
图标 Lucide Icons, Tabler Icons -
认证 Clerk -
语言 TypeScript 5.9.3
代码质量 ESLint + Prettier -

代码组成

  • TypeScript: 98.0%
  • CSS: 1.2%
  • 其他: 0.8%

4. 架构概述

4.1 目录结构

shadcn-admin/
├── .github/              # GitHub 工作流和文档
├── public/images/        # 静态图片资源
├── src/
│   ├── assets/           # 资源文件
│   ├── components/       # 通用组件
│   │   ├── data-table/   # 数据表格组件
│   │   ├── layout/       # 布局组件
│   │   └── ui/           # 基础 UI 组件 (30+)
│   ├── config/           # 配置文件
│   ├── context/          # React Context Providers
│   ├── features/         # 功能模块 (按功能划分)
│   ├── hooks/            # 自定义 Hooks
│   ├── lib/              # 工具函数
│   ├── routes/           # 路由定义
│   ├── stores/           # Zustand 状态存储
│   ├── styles/           # 样式文件
│   ├── main.tsx          # 应用入口
│   └── routeTree.gen.ts  # 自动生成的路由树
├── vite.config.ts        # Vite 配置
├── tsconfig.json         # TypeScript 配置
└── package.json          # 项目依赖

4.2 功能模块

项目采用 Feature-based 架构，每个功能模块独立组织：

📊 dashboard/ - 仪表盘
  • components/overview.tsx - 概览组件
  • components/analytics.tsx - 分析组件
  • components/analytics-chart.tsx - 分析图表
  • components/recent-sales.tsx - 近期销售
  • index.tsx - 模块入口
🔐 auth/ - 认证模块
  • sign-in/ - 登录页面
  • sign-up/ - 注册页面
  • forgot-password/ - 忘记密码
  • otp/ - OTP 验证
  • auth-layout.tsx - 认证布局
👥 users/ - 用户管理
  • components/ - 用户相关 UI 组件
  • data/ - 用户数据/类型定义
  • index.tsx - 模块入口
✅ tasks/ - 任务管理
  • components/ - 任务相关 UI 组件
  • data/ - 任务数据/类型定义
  • index.tsx - 模块入口
💬 chats/ - 聊天功能
  • components/ - 聊天 UI 组件
  • data/ - 聊天数据
  • index.tsx - 模块入口
⚙️ settings/ - 设置模块
  • account/ - 账户设置
  • appearance/ - 外观设置
  • display/ - 显示设置
  • notifications/ - 通知设置
  • profile/ - 个人资料
  • components/ - 共享组件
❌ errors/ - 错误页面
  • not-found-error.tsx - 404 页面
  • forbidden.tsx - 403 禁止访问
  • unauthorized-error.tsx - 401 未授权
  • general-error.tsx - 通用错误
  • maintenance-error.tsx - 维护页面
📱 apps/ - 应用管理

应用列表和管理页面

4.3 组件系统

UI 基础组件 (30个)

基于 Shadcn UI，包含：

alert-dialog, alert, avatar, badge, button, calendar, card,
checkbox, collapsible, command, dialog, dropdown-menu, form,
input-otp, input, label, popover, radio-group, scroll-area,
select, separator, sheet, sidebar, skeleton, sonner, switch,
table, tabs, textarea, tooltip

Data Table 组件

组件 功能
bulk-actions.tsx 批量操作工具栏
column-header.tsx 列标题（支持排序）
faceted-filter.tsx 多选筛选器
pagination.tsx 分页控件
toolbar.tsx 表格工具栏
view-options.tsx 列可见性控制

Layout 布局组件

组件 功能
app-sidebar.tsx 应用侧边栏
header.tsx 页面头部
top-nav.tsx 顶部导航
nav-group.tsx 导航分组
nav-user.tsx 用户导航
team-switcher.tsx 团队切换器
authenticated-layout.tsx 认证布局包装

Context Providers

  • theme-provider.tsx - 主题管理
  • direction-provider.tsx - RTL/LTR 方向
  • font-provider.tsx - 字体配置
  • layout-provider.tsx - 布局状态
  • search-provider.tsx - 搜索功能

Custom Hooks

  • use-dialog-state.tsx - 对话框状态管理
  • use-mobile.tsx - 移动端检测
  • use-table-url-state.ts - 表格状态与 URL 同步

5. 安装配置

环境要求

  • Node.js 18+
  • pnpm (推荐) / npm / yarn

安装步骤

bash# 克隆仓库
git clone https://github.com/satnaing/shadcn-admin.git

# 进入项目目录
cd shadcn-admin

# 安装依赖
pnpm install

# 启动开发服务器
pnpm run dev

可用脚本

命令 说明
pnpm dev 启动开发服务器
pnpm build 构建生产版本
pnpm preview 预览生产构建
pnpm lint 运行 ESLint 检查
pnpm format 格式化代码
pnpm format:check 检查代码格式
pnpm knip 检测未使用的文件和依赖

6. 页面路由

路由结构

src/routes/
├── (auth)/              # 认证相关页面（公开）
├── (errors)/            # 错误页面
├── _authenticated/      # 需要认证的页面
│   ├── index.tsx        # 仪表盘首页
│   ├── apps/            # 应用管理
│   ├── chats/           # 聊天功能
│   ├── errors/          # 错误演示
│   ├── help-center/     # 帮助中心
│   ├── settings/        # 设置页面
│   │   ├── account.tsx
│   │   ├── appearance.tsx
│   │   ├── display.tsx
│   │   └── notifications.tsx
│   ├── tasks/           # 任务管理
│   └── users/           # 用户管理
├── clerk/               # Clerk 认证路由
└── __root.tsx           # 根路由配置

预置页面列表

页面 路径 功能
Dashboard / 仪表盘概览、分析图表
Users /users 用户列表、CRUD 操作
Tasks /tasks 任务管理
Chats /chats 聊天界面
Apps /apps 应用列表
Settings /settings 账户、外观、通知设置
Help Center /help-center 帮助文档
Sign In /sign-in 登录页面
Sign Up /sign-up 注册页面
404 /404 页面未找到
403 /403 禁止访问
500 /500 服务器错误
Maintenance /maintenance 维护页面

7. 自定义组件

⚠️
重要提示
部分 Shadcn UI 组件已被自定义修改。如果使用 shadcn CLI 更新组件，需要手动合并这些修改。

通用修改的组件

这些组件有一般性的自定义修改：

  • scroll-area
  • sonner
  • separator

RTL 优化的组件

这些组件针对 RTL (从右到左) 布局进行了优化：

  • alert-dialog
  • calendar
  • command
  • dialog
  • dropdown-menu
  • select
  • table
  • sheet
  • sidebar
  • switch

8. 版本历史

v2.2.1 Latest (2025-11-06)
  • 更新认证布局的 data attribute class
  • 调整登出按钮样式
v2.2.0 (2025-10-09)
  • 新增分析仪表盘标签页
  • RTL 模式改进
  • 升级 lucide-react 依赖
v2.1.0 (2025-08-23)
  • 增强数据表格分页功能
  • 优化认证流程
  • 新增登出确认对话框
v2.0.0 Breaking (2025-08-16)
  • Breaking: CSS 结构重构
  • 实现 RTL 支持
  • 新增数据表格批量操作工具栏
v1.4.0 (2025-05-25)
  • 集成 Clerk 认证
  • 新增受保护路由
v1.0.0 (2024-12-09)
  • 首个正式版本
  • 采用 Feature-based 架构
  • 实现核心 CRUD 操作
  • 全局搜索功能

完整版本历史请查看 CHANGELOG.md