component-search

组件搜索

搜索 21st.dev 注册表中的生产就绪型 React 组件。返回按相关性排序的结果，包含代码、预览和安装说明。

component-search animated pricing table
component-search sidebar with collapsible sections
component-search dark mode toggle switch

工作原理

Query: "animated pricing table with monthly/annual toggle"
  │
  ▼
┌──────────────────────────────┐
│ 21st.dev Magic MCP           │  Search the 21st.dev developer registry
│ @21st-dev/magic              │  Filter: React, Tailwind, shadcn
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ Results (ranked by relevance)│
│                              │
│ 1. PricingToggle (98% match) │  ★ 2.3K views · shadcn/ui
│ 2. PricingCards (87% match)  │  ★ 1.8K views · Radix
│ 3. AnimatedPricing (82%)     │  ★ 950 views · Motion
└──────────────────────────────┘

步骤 0：解析查询

QUERY = ""  # Component description

# 1. Create main task IMMEDIATELY
TaskCreate(subject="Component search: {QUERY}", description="Search 21st.dev registry", activeForm="Searching for {QUERY}")

# 2. Create subtasks for each phase
TaskCreate(subject="Parse query and detect project context", activeForm="Detecting project context")  # id=2
TaskCreate(subject="Search component registry", activeForm="Searching registry")                      # id=3
TaskCreate(subject="Present and deliver results", activeForm="Presenting results")                    # id=4

# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"])  # Search needs project context first
TaskUpdate(taskId="4", addBlockedBy=["3"])  # Results need search done

# 4. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done — repeat for each subtask

# Detect project context for framework filtering
Glob("**/package.json")
# Read to determine: React version, Tailwind, shadcn/ui, styling approach

# Detect shadcn/ui style for result ranking
Glob("**/components.json")
# Read → "style" field (e.g., "radix-luma", "base-nova")
# Used to prefer components matching the project's visual language

步骤 1：搜索注册表

先浏览，让用户来选

原因在于选择，而非成本。 搜索结果会提供预览图片、视频、作者和 installCommand——足以让人一眼认出合适的组件，但模型做不到。用户想要的是八个“命令面板”搜索结果中的哪一个，模型无法猜中；这正是这套流程要避免的问题，而且无论使用哪个定价层级，这个问题都存在。

如果可以使用 21st-dev-magic MCP（实际流程）：

# 1. BROWSE. Prefer search_picker: same params and results as search, but it
#    renders an inline picker so the USER chooses. Do not pre-filter to one
#    result on their behalf — show the options.
mcp__21st-dev-magic__search_picker(query="{QUERY}", type="component", limit=8)

# 2. PICK — the user selects. Stop here and wait.

# 3. RETRIEVE — the chosen component.
mcp__21st-dev-magic__get_component(id=<demo id from the chosen result>)

• 如果用户只想知道某个组件是否存在，或想要安装命令，在步骤 1 后停止——搜索已经给出了答案。
• search 会返回包含 ?api_key=$API_KEY_21ST 的 installCommand。这与 MCP 的 TWENTY_FIRST_API_KEY 是不同的环境变量；如果 npx shadcn add 授权失败，说明环境中缺少该变量。

定价层级——先检查，不要想当然

get_component 是唯一按次计费的工具；search、search_picker、search_logo、get_theme 以及所有列表／元数据工具在所有层级中均不计费。

请调用 get_usage，而不要假设有使用上限。 它会返回 tier 和 freeRetrievalsRemaining（无限使用时两者均为 null）。

tier	get_component
free	每天 2 次——将每次检索都视为当天的预算：绝不臆测调用、绝不循环调用、绝不为了“比较”而调用
paid	无限——比较两个候选项没有问题；但仍须执行选择步骤

本文于 2026-08-16 根据免费账户编写，并于 2026-08-17 在账户升级为付费后修正：原文以每天 2 次的上限为依据阐述流程，因此上限解除后，内容看起来立刻就过时了。上限只是限制；让用户选择才是设计原则。

如果无法使用 21st-dev-magic（备用方案）：

# Genuine fallback ONLY — scraping returns no ids, no install commands, and
# no structured metadata. If the MCP is configured, you should never be here.
WebSearch("site:21st.dev {QUERY} React component")
# Or browse the registry
WebFetch("https://21st.dev", "Search for: {QUERY}")

替代生成流程——v0.app MCP（2026）： 如果注册表中没有匹配的组件，请改用 v0.app MCP 服务通过 AI 生成，而不是使用 WebFetch 抓取：

# If @vercel/v0-mcp is available
# v0.app generates from the same query and can pin to shadcn style
# (e.g., luma / nova / lyra) via `shadcn apply` after download.

这是一个生成流程，而不是注册表搜索——结果不会包含浏览量或星标。尽可能优先搜索注册表，以获取经过实战检验的组件；只有注册表中找不到时才使用 v0.app。

步骤 2：展示结果

展示排名前 3 的匹配项，包含：

• 组件名称和描述
• 匹配相关性评分
• 热度（浏览量／收藏数）
• 框架兼容性
• 预览（如有）
• 安装命令

AskUserQuestion(questions=[{
  "question": "Which component to use?",
  "header": "Component",
  "options": [
    {"label": "{name_1} (Recommended)", "description": "{desc_1} — {views_1} views"},
    {"label": "{name_2}", "description": "{desc_2} — {views_2} views"},
    {"label": "{name_3}", "description": "{desc_3} — {views_3} views"},
    {"label": "None — generate from scratch", "description": "Build a custom component instead"}
  ],
  "multiSelect": false
}])

步骤 3：交付组件

对于选定的组件：

1. 展示完整源代码
2. 列出依赖项（npm install 命令）
3. 注明任何必需的 peer 依赖项（Radix、Motion 等）
4. 指出可自定义的部分（属性、令牌、插槽）

框架兼容性

项目技术栈	搜索筛选条件	备注
React + Tailwind	默认——覆盖面最佳	大多数 21st.dev 组件
React + CSS Modules	筛选非 Tailwind 组件	结果较少
Next.js App Router	优先选择兼容 RSC 的组件	检查 "use client" 指令
Vue / Svelte	不支持	21st.dev 仅支持 React
shadcn/ui 风格	匹配视觉语言	Luma→圆角／胶囊形，Nova→紧凑，Lyra→锐利

了解 shadcn v4 风格： 当 components.json 中包含样式（例如 "radix-luma"）时，优先选择视觉语言相匹配的组件——Luma 使用圆角胶囊形，Nova／Mira 使用紧凑布局，Lyra 使用锐利边缘。安装后可以调整组件，但匹配度越高，需要的自定义工作就越少。

相关技能

• ork:design-to-code — 从完整模型稿到组件的工作流（使用此技能）
• ork:design-system-tokens — 将组件调整为符合项目令牌
• ork:ui-components — 组件库模式