--- name: Component Search slug: component-search category: Frontend description: Component Search finds production-ready React components in the 21st.dev registry from natural-language queries. Use it to look up UI building blocks, compare alternatives, and get install instructions. github: "https://github.com/yonatangross/orchestkit/tree/main/src/skills/component-search" language: TypeScript stars: 225 forks: 24 install: "npx degit https://github.com/yonatangross/orchestkit/tree/main/src/skills/component-search ~/.claude/skills/component-search" installs_to: ~/.claude/skills/component-search source_path: src/skills/component-search/SKILL.md collection_size: 25 category_size: 621 collection_url: "https://dirskills.com/collections/yonatangross/orchestkit" added: 2026-09-03T06:05:17.174Z last_synced: 2026-09-03T06:05:17.174Z canonical_url: "https://dirskills.com/skills/component-search" --- # Component Search Component Search finds production-ready React components in the 21st.dev registry from natural-language queries. Use it to look up UI building blocks, compare alternatives, and get install instructions. **Install:** ```bash npx degit https://github.com/yonatangross/orchestkit/tree/main/src/skills/component-search ~/.claude/skills/component-search ``` ## README # Component Search Search 21st.dev's registry of production-ready React components. Returns ranked results with code, previews, and install instructions. ```bash /ork:component-search animated pricing table /ork:component-search sidebar with collapsible sections /ork: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 ```python 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):** ```python # 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=) ``` - 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: never speculative, never in a loop, never "to compare" | | `paid` | unlimited — comparing two candidates is fine; the picker step still applies | Written 2026-08-16 against a free account and corrected 2026-08-17 when the account went paid: the original text argued the flow from the 2/day cap, which made it read as obsolete the moment the cap lifted. The cap is a constraint; letting the user choose is the design. **If 21st-dev-magic is NOT available (fallback):** ```python # 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}") ``` **Alternative generation path — v0.app MCP (2026):** When the registry doesn't have a matching component, fall back to AI generation via the v0.app MCP server rather than WebFetch scraping: ```python # 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. ``` This is a **generation** path, not a registry search — results will not have view counts or stars. Prefer registry search when possible so you get battle-tested components; use v0.app only when the registry misses. ## Step 2: Present Results Show top 3 matches with: - Component name and description - Match relevance score - Popularity (views/bookmarks) - Framework compatibility - Preview (if available) - Install command ```python 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 }]) ``` ## Step 3: Deliver Component For the selected component: 1. Show the full source code 2. List dependencies (`npm install` commands) 3. Note any required peer dependencies (Radix, Motion, etc.) 4. Highlight customization points (props, tokens, slots) ## Framework Compatibility | Project Stack | Search Filter | Notes | |--------------|---------------|-------| | React + Tailwind | Default — best coverage | Most 21st.dev components | | React + CSS Modules | Filter non-Tailwind | Fewer results | | Next.js App Router | Prefer RSC-compatible | Check "use client" directives | | Vue / Svelte | Not supported | 21st.dev is React-only | | shadcn/ui style | Match visual language | Luma→rounded/pill, Nova→compact, Lyra→sharp | **shadcn v4 style awareness:** When `components.json` has a style (e.g., `"radix-luma"`), prefer components whose visual language matches — rounded pill shapes for Luma, dense layouts for Nova/Mira, sharp edges for Lyra. Components can be adapted post-install, but a closer match reduces customization work. ## Related Skills - `ork:design-to-code` — Full mockup-to-component pipeline (uses this skill) - `ork:design-system-tokens` — Adapt components to project tokens - `ork:ui-components` — Component library patterns