21st Dev

21st.dev

21st.dev is the "npm for design engineers" — an open-source community registry (MIT) of high-quality React + Tailwind components, blocks, and hooks. It is shadcn-compatible: every component is installed with the standard npx shadcn@latest add CLI, just pointed at a 21st.dev URL.

Prerequisites

• Node 18+ and npx
• A Next.js / Vite / React Router / Astro project
• Tailwind CSS v3 or v4 (Tailwind 4 requires shadcn CLI v4+, March 2026 or newer)
• React 18 or 19
• shadcn initialized once (writes components.json, src/lib/utils.ts, src/components/ui/button.tsx, and shadcn theme tokens into globals.css)

One-time setup (per project)

# Initialize shadcn — creates components.json, ui/, lib/utils.ts, theme tokens
cd <project-root>
npx --yes shadcn@latest init -d --force

-d uses defaults (Next.js template, base-nova preset). --force overwrites any prior config.

Important — the init step rewrites --background, --foreground, --primary, --accent in globals.css to neutral oklch values. If your project already has brand colors mapped to those CSS variables (Weblyfe does — emerald + gold + snow), you must restore the brand mappings immediately after init:

:root {
  /* Keep brand vars */
  --brand-emerald: #247459;
  --brand-gold: #DFB771;
  --brand-snow: #F6FEFC;
  /* ... */

  /* Re-map shadcn slots to brand */
  --background: var(--brand-snow);
  --foreground: var(--brand-green-goblin);
  --primary: var(--brand-emerald);
  --accent: var(--brand-gold);
  /* keep the rest of shadcn's tokens (card, popover, secondary, border, ring, etc.) */
}

Also restore --font-sans if you use a custom font variable (shadcn replaces it with var(--font-sans)):

@theme inline {
  --font-sans: var(--font-rethink), system-ui, sans-serif;
  --font-heading: var(--font-rethink), system-ui, sans-serif;
}

Adding a 21st.dev component

Browse https://21st.dev → pick a component → click "Code" / copy the install URL. Then:

npx --yes shadcn@latest add "https://21st.dev/r/<author>/<component>" --yes

The CLI:

1. Creates src/components/ui/<component>.tsx
2. Installs npm dependencies (e.g. framer-motion, @radix-ui/*)
3. Patches globals.css with any required @theme keyframes / variables

Import with the alias:

import { Marquee } from "@/components/ui/marquee";

Component catalogue — best for Weblyfe homepage

Browse the full registry at https://21st.dev. Here are the picks most relevant to the Appie hero + TIPS structure:

Many authors publish multiple variants (e.g. magicui has hero-pill, hero-video-dialog, hero-section). Always preview on 21st.dev before installing.

Discovery workflow

1. Open https://21st.dev/s/ (e.g. /s/hero, /s/pricing, /s/testimonial)
2. Filter by Popular or Featured
3. Click a card → preview the live demo
4. Click "Code" → copy the npx shadcn@latest add URL
5. Paste into terminal in project root

For semantic search across the registry, the Magic Console (https://21st.dev/magic/console) offers free semantic component search and SVG icon search. Generation features (auto-creating bespoke variants) require the $20/month Pro plan but are not needed for installing existing components.

Magic MCP (optional — paid feature)

For prompt-driven component generation inside Claude Code:

npx --yes @21st-dev/cli@latest install claude --api-key <KEY>

API keys come from https://21st.dev/magic/console. The MCP exposes /ui for prompt-to-component generation. This is not required — the free npx shadcn add <url> flow gives you every published component on the registry.

Stack-specific notes for weblyfe-ai

• Tailwind 4: Already wired. shadcn v4 CLI (March 2026+) handles @theme inline and @custom-variant dark automatically.
• Next.js 16 + React 19: Fully supported. shadcn writes Server-Component-safe code by default.
• framer-motion 12: Already installed; many 21st.dev components depend on it and will reuse the existing version rather than re-installing.
• Brand preservation: After every shadcn add, scan globals.css for newly-added --background / --primary overrides and re-map to brand vars if needed. The CLI usually only appends @theme rules and keyframes (safe), but init is the one to watch.
• Path aliases: Components land in src/components/ui/*.tsx and import via @/components/ui/* and @/lib/utils. Already set up in tsconfig.json.
• Dark mode: shadcn writes a .dark block. We currently do not use dark mode on weblyfe.ai — leave the block in place but do not toggle the class.

Smoke-test pattern

Always verify a new install with a throwaway page before integrating into the homepage:

// src/app/labs/<component-name>/page.tsx
import { NewComponent } from "@/components/ui/new-component";

export default function Lab() {
  return (
    <main className="min-h-screen container py-24">
      <NewComponent />
    </main>
  );
}

Then npm run build to confirm it compiles end-to-end. Once verified, port the component into the real homepage section and delete the lab page (or keep /labs/* as a private gallery).

Licensing

21st.dev itself is MIT. Individual components inherit each author's license — check the component page footer. Most are MIT/Apache and safe for commercial use. Aceternity UI, Magic UI, originui, kokonutui are all MIT.

Red flags

• Some components depend on heavy 3D libs (three, @react-three/fiber, ogl). Check the dependencies block on the 21st.dev component page before installing — the CLI will pull them in silently.
• A few authors ship components that import paid Aceternity Pro assets. The free preview will install but render placeholder text. Read the component page carefully.
• If a component references cn from @/lib/utils and your project uses a different alias, edit the import after install.

Agent Elements — AI agent UI components (NEW June 2026)

21st.dev now ships Agent Elements — 25 purpose-built shadcn/ui components for AI agent UIs (chat surfaces, tool cards, plan approvals). This is the first component library with a bundled SKILL.md so AI coding agents already know the API.

# Install the full chat UI
npx shadcn@latest add https://agent-elements.21st.dev/r/agent-chat.json

# Or individual tool cards
npx shadcn@latest add https://agent-elements.21st.dev/r/edit-tool.json
npx shadcn@latest add https://agent-elements.21st.dev/r/bash-tool.json
npx shadcn@latest add https://agent-elements.21st.dev/r/plan-tool.json

# Teach AI agents (Claude/Cursor/Codex) how to use Agent Elements
npx skills add 21st-dev/agent-elements

Component catalog: AgentChat, MessageList, Markdown, InputBar, ModeSelector, ModelPicker, BashTool, EditTool (diff + approve/reject), SearchTool, TodoTool, PlanTool, SubagentTool, McpTool, ThinkingTool, QuestionTool, TextShimmer, SpiralLoader.

Use Agent Elements when building any agent-facing web UI — chat interfaces, tool execution dashboards, plan approval flows. Built on shadcn/ui, works with any AI SDK. Open source (MIT). Docs: https://agent-elements.21st.dev

Component Libraries — private team registries (NEW April-June 2026)

Publish your team's components into a private shadcn-compatible registry that AI agents install from instead of regenerating:

# One-time setup
npx @21st-dev/registry install-skill --global

# Publish a component
npx @21st-dev/registry publish components/my-button.tsx

# Agent installs from registry (paste into CLAUDE.md rules)
npx @21st-dev/registry add @team/my-button

Why this matters for AI agents: Instead of regenerating the same button/card/form for every project, agents pull from the team registry. One line of shell rules in CLAUDE.md teaches them to prefer npx @21st-dev/registry add over generation. Supports semantic search, multi-registry organization, per-component visibility (public/unlisted/private). MCP tool integration planned.

npm: @21st-dev/registry (v0.0.9, July 2026), MIT. Docs: https://21st.dev/community/blog/component-libraries

References

• Registry: https://21st.dev
• Agent Elements: https://agent-elements.21st.dev | GitHub: https://github.com/21st-dev/agent-elements (MIT)
• Component Libraries: https://21st.dev/community/blog/component-libraries
• @21st-dev/registry CLI: https://www.npmjs.com/package/@21st-dev/registry (MIT)
• GitHub: https://github.com/serafimcloud/21st (MIT)
• Magic MCP (paid): https://github.com/21st-dev/magic-mcp
• shadcn v4 changelog: https://ui.shadcn.com/docs/changelog/2026-03-cli-v4
• Tailwind 4 + shadcn: https://ui.shadcn.com/docs/tailwind-v4