name: shadcn-components
description: Manage Shadcn UI components: Add, Update, and Create custom components following best practices.

Shadcn Components

Use this skill to add new components from the library or create custom components that align with Shadcn's architecture.

Documentation

• Shadcn CLI

Workflow

1. Prerequisites

• Verify Initialization: Check if components.json exists in the project root.
• If Missing: Stop and run the shadcn-setup skill first. You cannot add components to an uninitialized project.

2. Add or Update Components

To install a component from the registry:

pnpm dlx shadcn@latest add [component-name]

• Overwrite: If the component exists and you are updating it, the CLI may ask to overwrite. Use --overwrite flag if you are certain.
• Multiple: You can add multiple components at once: pnpm dlx shadcn@latest add button card input.

2. Create Custom Components (The "Shadcn Way")

When creating a new component that isn't in the registry, follow these patterns:

A. Structure

Start with a file in components/ui/ (or configured path).

B. Imports

MUST import the cn utility for class merging.

import * as React from "react"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "@/lib/utils"

C. Variant Definitions with cva

Define visual variants using class-variance-authority.

const badgeVariants = cva(
  "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2",
  {
    variants: {
      variant: {
        default: "border-transparent bg-primary text-primary-foreground hover:bg-primary/80",
        secondary: "border-transparent bg-secondary text-secondary-foreground hover:bg-secondary/80",
        destructive: "border-transparent bg-destructive text-destructive-foreground hover:bg-destructive/80",
        outline: "text-foreground",
      },
    },
    defaultVariants: {
      variant: "default",
    },
  }
)

D. Component Definition

• Export the interface extending HTML attributes.
• Include className and variant props.
• Use cn() to merge className prop with variants.
• Set displayName for debugging if needed.

export interface BadgeProps
  extends React.HTMLAttributes<HTMLDivElement>,
    VariantProps<typeof badgeVariants> {}

function Badge({ className, variant, ...props }: BadgeProps) {
  return (
    <div className={cn(badgeVariants({ variant }), className)} {...props} />
  )
}

export { Badge, badgeVariants }

3. Anti-Patterns ❌

• Strings without cn(): Never manually concat strings like `bg-red-500 ${className}`. Always use cn().
• Ignoring Props: Always spread ...props to the underlying element to ensure accessibility attributes and event listeners pass through.

References

• Form Patterns (Zod + HookForm)
• Data Tables (TanStack)