shadcn Component Discovery
shadcn 组件查找工具
Stop reinventing the wheel. Search 1,500+ existing shadcn components before building custom.
不要重复造轮子。在自定义构建之前，先搜索1500+个已有的shadcn组件。
ALWAYS search before building. The shadcn ecosystem has components for almost everything. A 5-second search can save hours of development.
始终先搜索再构建。 shadcn生态系统几乎包含所有场景的组件。一次5秒钟的搜索能为你节省数小时的开发时间。
When to Use This Skill
何时使用该工具
Proactive Triggers (Search Automatically)
主动触发场景（自动搜索）
Activate this skill BEFORE writing component code when:
- Building any UI component (tables, forms, modals, etc.)
- Creating page layouts or sections
- Adding animations or interactions
- Implementing common patterns (auth, dashboards, settings)
在编写组件代码之前激活该工具，适用于以下场景：
- 构建任何UI组件（表格、表单、模态框等）
- 创建页面布局或区块
- 添加动画或交互效果
- 实现常见模式（认证、仪表盘、设置页面）
Explicit Triggers (User Requests)
显式触发场景（用户请求）
Activate when user says things like:
- "Find a component for..."
- "Is there a shadcn component for..."
- "Search registries for..."
- "What components exist for..."
- , ,
当用户说出以下内容时激活：
- "找一个用于……的组件"
- "有没有适用于……的shadcn组件？"
- "在组件库中搜索……"
- "有哪些适用于……的组件？"
- , ,
Step 1: Identify What's Needed
步骤1：明确需求
Before searching, clarify:
- What functionality is needed?
- What style/aesthetic? (animated, minimal, accessible, etc.)
- Any specific requirements? (drag-drop, keyboard nav, etc.)
搜索之前，先理清：
- 需要什么功能？
- 风格/审美要求？（动画效果、极简风、无障碍等）
- 有没有特定需求？（拖拽、键盘导航等）
Step 2: Search Registries
步骤2：搜索组件库
With shadcn MCP configured (recommended):
1. mcp__shadcn__search_items_in_registries
- registries: ["@shadcn", "@animate-ui", "@diceui", "@blocks", "@reui"]
- query: [search term]
- limit: 10
2. For promising results, get details:
mcp__shadcn__view_items_in_registries
- items: ["@registry/component-name"]
3. For code examples:
mcp__shadcn__get_item_examples_from_registries
- query: "component-demo"
4. Get install command:
mcp__shadcn__get_add_command_for_items
- items: ["@registry/component-name"]
Without MCP:
- Consult references/registries.md for registry recommendations
- Provide links to browse manually
- Suggest adding shadcn MCP for full search capabilities
已配置shadcn MCP（推荐）：
1. mcp__shadcn__search_items_in_registries
- registries: ["@shadcn", "@animate-ui", "@diceui", "@blocks", "@reui"]
- query: [搜索关键词]
- limit: 10
2. 对于有潜力的结果，获取详情：
mcp__shadcn__view_items_in_registries
- items: ["@registry/component-name"]
3. 获取代码示例：
mcp__shadcn__get_item_examples_from_registries
- query: "component-demo"
4. 获取安装命令：
mcp__shadcn__get_add_command_for_items
- items: ["@registry/component-name"]
未配置MCP时：
- 参考 references/registries.md 获取组件库推荐
- 提供手动浏览链接
- 建议配置shadcn MCP以获得完整搜索功能
Step 3: Present Findings (Adaptive Format)
步骤3：呈现结果（自适应格式）
Choose response format based on context:
Quick Check (During Build)
快速检查（构建过程中）
Use when proactively checking before building. Minimal interruption.
markdown
Before building a custom [component], I found existing options:
1. **@registry/component-name** - [brief description]
2. **@registry/other-option** - [brief description]
→ Install one of these, or build custom?
适用于构建前主动检查的场景，尽量减少干扰。
markdown
在构建自定义[组件]之前，我找到了以下现有选项：
1. **@registry/component-name** - [简要描述]
2. **@registry/other-option** - [简要描述]
→ 是安装其中一个，还是进行自定义构建？
Standard Discovery (Explicit Search)
标准查找结果（显式搜索）
Use when user explicitly asks to find components.
Component Discovery: "[search term]"
组件查找结果："[搜索关键词]"
Found [N] matches across [N] registries. Top recommendations:
在[N]个组件库中找到**[N]个匹配结果**。推荐选项如下：
1. @registry/component-name ⭐ Recommended
1. @registry/component-name ⭐ 推荐
[Description of what it does]
- Why it fits: [reason this matches the need]
- Features: [key capabilities]
bash
npx shadcn@latest add @registry/component-name
[组件功能描述]
- 适配原因： [符合需求的理由]
- 特性： [核心功能]
bash
npx shadcn@latest add @registry/component-name
2. @registry/alternative
2. @registry/alternative
[Description]
bash
npx shadcn@latest add @registry/alternative
[组件描述]
bash
npx shadcn@latest add @registry/alternative
3. @registry/another-option
3. @registry/another-option
[Description]
bash
npx shadcn@latest add @registry/another-option
Options: [1] Install recommended | [2-3] Install alternative | [More] See all results | [Custom] Build from scratch
[组件描述]
bash
npx shadcn@latest add @registry/another-option
可选操作： [1] 安装推荐组件 | [2-3] 安装替代组件 | [更多] 查看全部结果 | [自定义] 从头构建
Detailed Comparison (Complex Choices)
详细对比（复杂选择场景）
Use when multiple good options exist and choice matters.
Component Discovery: "[search term]"
组件查找结果："[搜索关键词]"
| Component | Registry | Best For | Complexity |
|---|
| option-1 | @registry | [use case] | Low/Med/High |
| option-2 | @registry | [use case] | Low/Med/High |
| option-3 | @registry | [use case] | Low/Med/High |
| 组件 | 组件库 | 最佳适用场景 | 复杂度 |
|---|
| option-1 | @registry | [使用场景] | 低/中/高 |
| option-2 | @registry | [使用场景] | 低/中/高 |
| option-3 | @registry | [使用场景] | 低/中/高 |
Recommendation: @registry/option-1
推荐：@registry/option-1
[Explain why this is the best fit for their specific needs]
Key features:
- ✅ [feature 1]
- ✅ [feature 2]
- ✅ [feature 3]
Install:
bash
npx shadcn@latest add @registry/option-1
Want to see a code example before deciding?
[解释为何该组件最契合你的特定需求]
核心特性：
安装命令：
bash
npx shadcn@latest add @registry/option-1
是否需要查看代码示例再做决定？
No MCP Fallback
未配置MCP时的回退方案
Use when shadcn MCP is not configured.
Component Discovery: "[search term]"
组件查找结果："[搜索关键词]"
⚡
Pro tip: Configure the
shadcn MCP for instant search across 1,500+ components with code examples and one-click installs.
Based on your needs, check these registries:
To enable full discovery:
⚡
小贴士： 配置
shadcn MCP 后，可即时搜索1500+个组件，还能获取代码示例和一键安装功能。
根据你的需求，可查看以下组件库：
启用完整查找功能：
Install shadcn MCP for your AI coding tool
为你的AI编码工具安装shadcn MCP
Or browse all registries: [registry.directory](https://registry.directory)
---
Should I build custom, or check these registries first?
或浏览全部组件库：[registry.directory](https://registry.directory)
---
是进行自定义构建，还是先查看这些组件库？
Step 4: Execute User Choice
步骤4：执行用户选择
Based on user selection:
- Install component: Run the add command, then customize as needed
- See more results: Show additional matches with pagination
- View example: Fetch and display code example
- Build custom: Proceed with custom implementation (still reference the existing component for patterns)
根据用户的选择：
- 安装组件： 运行安装命令，之后按需自定义
- 查看更多结果： 分页展示更多匹配项
- 查看示例： 获取并展示代码示例
- 自定义构建： 继续进行自定义实现（仍可参考现有组件的设计模式）
Effective Search Terms
高效搜索关键词
| Looking for... | Try searching... |
|---|
| Data display | , , |
| User input | , , , |
| Navigation | , , , |
| Feedback | , , |
| Overlays | , , , |
| Media | , , |
| Animation | , , |
| Layout | , , , |
| 需求 | 尝试搜索…… |
|---|
| 数据展示 | , , |
| 用户输入 | , , , |
| 导航 | , , , |
| 反馈提示 | , , |
| 浮层 | , , , |
| 媒体内容 | , , |
| 动画 | , , |
| 布局 | , , , |
Registry Specialties
组件库专长
Quick reference for which registries to prioritize:
| Need | Check First |
|---|
| Basic UI primitives | @shadcn |
| Page sections/blocks | @blocks |
| Data tables/grids | @reui |
| Animations | @animate-ui, Magic UI |
| AI/Chat interfaces | AI Elements, assistant-ui |
| Accessibility | @diceui, JollyUI |
See references/registries.md for complete catalog.
快速参考应优先选择哪些组件库：
| 需求 | 优先查看 |
|---|
| 基础UI原语 | @shadcn |
| 页面区块/模块 | @blocks |
| 数据表格/网格 | @reui |
| 动画效果 | @animate-ui, Magic UI |
| AI/聊天界面 | AI Elements, assistant-ui |
| 无障碍设计 | @diceui, JollyUI |
完整组件库目录请查看 references/registries.md。
Response Requirements
响应要求
Every discovery response MUST include:
- Search term used - What was searched
- Match count - How many results found
- Top 3 recommendations - Best matches with:
- Component name and registry
- Brief description
- Why it fits the need
- Install command
- Clear options - What user can do next
- Recommendation - Which one to use (when clear winner exists)
每次查找响应必须包含：
- 使用的搜索关键词 - 搜索的内容
- 匹配数量 - 找到的结果数
- Top3推荐 - 最佳匹配项，包含：
- 组件名称和所属组件库
- 简要描述
- 适配需求的理由
- 安装命令
- 清晰的可选操作 - 用户下一步可执行的操作
- 推荐意见 - 当存在明显最优选项时，指明选择哪一个
Example 1: Proactive Check
示例1：主动检查
Situation: User asks "Add a data table to show user accounts"
Agent response:
markdown
Before building a custom data table, I found these existing options:
1. **@reui/data-grid-table** - Full-featured grid with sorting, filtering, pagination
2. **@blocks/table-05** - Pre-styled data table block
3. **@shadcn/table** - Basic table primitives
→ The @reui/data-grid-table looks perfect for user accounts. Install it?
场景： 用户要求“添加一个数据表格展示用户账户”
Agent响应：
markdown
在构建自定义数据表格之前，我找到了以下现有选项：
1. **@reui/data-grid-table** - 全功能网格，支持排序、筛选、分页
2. **@blocks/table-05** - 预样式化的数据表格区块
3. **@shadcn/table** - 基础表格原语
→ @reui/data-grid-table看起来非常适合展示用户账户信息。是否安装该组件？
Example 2: Explicit Search
示例2：显式搜索
Situation: User asks "Find me an animated accordion"
Agent response:
场景： 用户要求“找一个带动画的手风琴组件”
Agent响应：
Component Discovery: "animated accordion"
组件查找结果："带动画的手风琴"
Found 8 matches across 5 registries. Top recommendations:
1. @animate-ui/components-base-accordion ⭐ Recommended
1. @animate-ui/components-base-accordion ⭐ 推荐
Smooth animated accordion with enter/exit transitions.
- Why it fits: Built-in animations, accessible, customizable timing
- Features: Keyboard nav, ARIA compliant, Motion powered
bash
npx shadcn@latest add @animate-ui/components-base-accordion
带有平滑进入/退出过渡动画的手风琴组件。
- 适配原因： 内置动画效果，支持无障碍访问，可自定义时长
- 特性： 键盘导航、符合ARIA标准、基于Motion实现
bash
npx shadcn@latest add @animate-ui/components-base-accordion
2. @shadcn/accordion
2. @shadcn/accordion
Standard accordion (no built-in animation).
- Why it fits: Simple, lightweight, easy to add custom animations
bash
npx shadcn@latest add @shadcn/accordion
Options: [1] Install animated | [2] Install basic + add animations | [Custom] Build from scratch
标准手风琴组件（无内置动画）。
bash
npx shadcn@latest add @shadcn/accordion
可选操作： [1] 安装带动画的组件 | [2] 安装基础组件+添加动画 | [自定义] 从头构建
Example 3: No Good Match
示例3：无匹配结果
Situation: Search returns no relevant results
Agent response:
Component Discovery: "quantum flux capacitor"
组件查找结果："量子通量电容器"
No existing components found for this specific need.
Closest matches:
- @shadcn/card - Could be adapted as a container
- @animate-ui/components-backgrounds-gradient - For visual effects
Since this is a unique component, I'll build it custom.
Want me to check any specific registries first, or proceed with custom build?
未找到符合该特定需求的现有组件。
最接近的匹配项：
- @shadcn/card - 可适配作为容器使用
- @animate-ui/components-backgrounds-gradient - 可用于实现视觉效果
由于这是一个独特的组件，我将进行自定义构建。
是否需要先查看特定组件库，还是直接开始自定义构建？
- Search BEFORE writing any component code
- Present multiple options when available
- Explain WHY each option fits (or doesn't)
- Include ready-to-run install commands
- Offer to show code examples
- 在编写任何组件代码之前先搜索
- 有多个选项时，全部呈现给用户
- 解释每个选项为何适配（或不适配）需求
- 包含可直接运行的安装命令
- 主动提供查看代码示例
- Skip searching because "it's faster to build"
- Present too many options (3-5 max)
- Forget to mention the install command
- Assume user wants the first result
- Build custom without at least checking first
- 因为“构建更快”而跳过搜索步骤
- 呈现过多选项（最多3-5个）
- 忘记提供安装命令
- 假设用户想要第一个搜索结果
- 至少先检查组件库再进行自定义构建