Component Registry

Registries Overview

Installation uses namespaced addresses (@namespace/item) — the --registry flag no longer exists in CLI v4.

Installation Commands

Standard shadcn/ui Components

# Single component
npx shadcn@latest add button

# Multiple components at once
npx shadcn@latest add button card input dialog

# Force overwrite existing files
npx shadcn@latest add button --overwrite

shadcn studio Components

# Component variant
npx shadcn@latest add @ss-components/button-01

# Block
npx shadcn@latest add @ss-blocks/hero-section-01

# Theme — install via init from the theme URL, or the @ss-themes namespace
npx shadcn@latest init "https://shadcnstudio.com/r/themes/[name].json"
npx shadcn@latest add @ss-themes/[name]

# Skip confirmation prompts
npx shadcn@latest add @ss-components/button-01 --yes

Inspect Before Installing

# View a registry item's contents without installing
npx shadcn@latest view @ss-blocks/hero-section-01

# See what an install would change, without writing files
npx shadcn@latest add button --dry-run

# Read a component's docs/API/examples in the terminal
npx shadcn@latest docs button

# Search a registry server-side
npx shadcn@latest search @shadcn -q "date picker"

Core Component Categories

Data Display

Form Inputs

Navigation & Layout

Feedback & Overlay

Data & Utility

Chat (June 2026)

Chat interface suite plus scroll-fade and shimmer CSS utilities:

npx shadcn@latest add message-scroller message bubble attachment marker

shadcn studio Block Categories

See references/shadcn-studio-components.md and references/shadcn-studio-blocks.md for detailed catalogs.

Community Registries (260+)

Beyond the standard shadcn/ui and shadcn studio registries, 260+ registries in the official directory provide specialized components:

Install from a community registry:

npx shadcn@latest add @magicui/shimmer-button
npx shadcn@latest add @aceternity/moving-border
npx shadcn@latest add @commercn/product-card-01

See the component-search skill for the full registry reference with URLs, setup instructions, and search workflow.

Where Components Are Installed

src/
├── components/
│   └── ui/                    # ← shadcn/ui components go here
│       ├── button.tsx
│       ├── card.tsx
│       ├── dialog.tsx
│       └── ...
├── components/
│   └── shadcn-studio/         # ← Studio blocks land here initially
│       └── blocks/
│           └── hero-section-01/
└── lib/
    └── utils.ts               # cn() helper

After installing studio blocks, move them to your preferred location:

# Move from studio default to your blocks directory
mv src/components/shadcn-studio/blocks/hero-section-01 src/components/blocks/hero-section-01

Common Installation Patterns

Dashboard Setup

npx shadcn@latest add card table tabs sidebar sheet dropdown-menu avatar badge separator skeleton chart

Form Setup

npx shadcn@latest add form input button select checkbox radio-group switch textarea label

Marketing Page Setup

npx shadcn@latest add button card badge separator navigation-menu
npx shadcn@latest add @ss-blocks/hero-section-01
npx shadcn@latest add @ss-blocks/feature-section-01
npx shadcn@latest add @ss-blocks/pricing-01

Authentication Setup

npx shadcn@latest add form input button label card
npx shadcn@latest add @ss-blocks/login-01

Component Composition

shadcn/ui components are building blocks. Compose them into feature components:

// components/user-profile-card.tsx
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
import { Badge } from "@/components/ui/badge"

export function UserProfileCard({ user }: { user: User }) {
  return (
    <Card>
      <CardHeader>
        <div className="flex items-center gap-4">
          <Avatar>
            <AvatarImage src={user.avatar} />
            <AvatarFallback>{user.initials}</AvatarFallback>
          </Avatar>
          <div>
            <CardTitle>{user.name}</CardTitle>
            <Badge variant={user.active ? "default" : "secondary"}>
              {user.role}
            </Badge>
          </div>
        </div>
      </CardHeader>
      <CardContent>{user.bio}</CardContent>
    </Card>
  )
}

shadcn v4: render Prop Instead of asChild

shadcn v4 uses @base-ui/react (Base UI) instead of Radix by default. The asChild prop does not exist on Base UI components — it will cause a TypeScript error. Use the render prop instead. This applies to all compound components (SheetTrigger, DialogTrigger, DropdownMenuTrigger, etc.). Radix-based projects (init -b radix) still use asChild.

Button as Link

The official Base UI Button docs explicitly warn: do NOT use <Button render={<a />} nativeButton={false} /> for links — Base UI's Button always applies role="button", which overrides link semantics. Use buttonVariants() on a plain <a> instead:

import { buttonVariants } from "@/components/ui/button"

// Correct — a real link with button styling
<a href="/dashboard" className={buttonVariants()}>Go to Dashboard</a>

// Wrong — role="button" breaks link semantics
// <Button nativeButton={false} render={<a href="/dashboard" />}>Go</Button>

// Wrong — asChild does NOT exist on Base UI components
// <Button asChild><a href="/dashboard">Go</a></Button>

Trigger Components (SheetTrigger, DialogTrigger, etc.)

When wrapping a custom element as a trigger, use render to compose the trigger with your component — this Base UI pattern remains correct:

import { Sheet, SheetTrigger, SheetContent } from "@/components/ui/sheet"
import { Button } from "@/components/ui/button"

// Correct — SheetTrigger renders as a Button
<SheetTrigger render={<Button variant="ghost" size="icon" />}>
  <Menu className="h-5 w-5" />
</SheetTrigger>

// Wrong — asChild does NOT exist on Base UI components
// <SheetTrigger asChild><Button>Open</Button></SheetTrigger>

Updating Components

To update to the latest version of a component, re-run the add command with --overwrite:

npx shadcn@latest add button --overwrite

This replaces the component file entirely. If you customized the component, back up your changes first.

What This Skill Does NOT Cover

• Initial shadcn/ui setup -- see setup skill
• MCP-based component discovery -- see mcp-tools skill
• Theme and color configuration -- see theme-configuration skill
• Project structure and architecture -- see project-scaffolding skill
• Community registry search and catalog -- see component-search skill