/component-search

name: component-search
license: MIT
compatibility: "Claude Code 2.1.251+. Optional: 21st-dev-magic MCP server."
description: "Search 21st.dev component registry for production-ready React components. Finds components by natural language description, filters by framework and style system, returns ranked results with install instructions. Use when looking for UI components, finding alternatives to existing components, or sourcing design system building blocks."
argument-hint: "[component description]"
tags: [components, 21st-dev, react, ui, search, registry, tailwind, shadcn]
context: fork
# user-typed commands stay interactive; CC >= 2.1.218 backgrounds forks by default (#3093)
background: false
version: 1.1.0
author: OrchestKit
user-invocable: true
complexity: simple
persuasion-type: collaborative
effort: low
model: sonnet
allowed-tools:
  - Read
  - Glob
  - Grep
  - WebFetch
  - WebSearch
  - AskUserQuestion
  - TaskCreate
  - TaskUpdate
  # 21st-dev-magic MCP. Without these the skill CANNOT reach the server it is
  # named after and silently degrades to the WebSearch/WebFetch scrape below.
  # Read-only surface by design: the catalog-mutating tools (submit_component,
  # edit_component, delete_*, bookmark writes) are deliberately NOT granted —
  # a search skill has no business publishing to or deleting from the registry.
  - mcp__21st-dev-magic__search_picker
  - mcp__21st-dev-magic__search
  - mcp__21st-dev-magic__get_component
  - mcp__21st-dev-magic__get_theme
  - mcp__21st-dev-magic__search_logo
  - mcp__21st-dev-magic__get_usage
  - TaskList
metadata:
  category: workflow-automation
  mcp-server: 21st-dev-magic
triggers:
  keywords: ["component search", "find component", "search components", "ui component", "react component", "21st.dev"]
  examples:
    - "search for a date picker component"
    - "find a modal component for React"
    - "are there any good table components on 21st.dev"
  anti-triggers: [implement, build, design, explore, brainstorm]

Component Search

Search 21st.dev's registry of production-ready React components. Returns ranked results with code, previews, and install instructions.

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

How It Works

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
└──────────────────────────────┘

Step 0: Parse Query

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

Step 1: Search Registry

Browse first, and let the USER pick

**The reason is choice, not cost.** Search returns a preview image, a video, the author and the `installCommand` — enough for a human to recognise the right component at a glance. The model cannot. Guessing which of eight "command palette" results the user meant is the failure mode this flow exists to prevent, and it stays a failure mode on every pricing tier.

**If 21st-dev-magic MCP is available (the real path):**

# 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>)

• If the user only needs to know *whether* something exists, or wants the install

command, **stop after step 1** — search already answered it.

• `search` returns an `installCommand` containing `?api_key=$API_KEY_21ST`. That

is a **different env var** from the MCP's `TWENTY_FIRST_API_KEY`; if `npx shadcn add` fails auth, that variable is missing from the environment.

Tier — check it, do not assume it

`get_component` is the only metered tool; `search`, `search_picker`, `search_logo`, `get_theme` and every list/metadata tool are unmetered on all tiers.

**Call `get_usage` rather than assuming a cap.** It returns `tier` plus `freeRetrievalsRemaining` (both `null` when unlimited).

| tier | `get_component` | |---|---| | `free` | **2 / day** — treat each retrieval as the day's budget: n