---
name: shadcnui-bb456eecacfe
description: Expert shadcn/ui assistance covering Radix UI primitives, Tailwind CSS styling, copy-paste architecture, and accessibility. Use when building modern React component systems and accessible design systems.
---

# shadcn/ui

shadcn/ui is not a component library; it's a **collection of reusable components** that you copy and paste into your apps. Built on Radix UI and Tailwind.

## When to Use

- **Modern Copy-Paste Component Architecture**: Full ownership of React UI components without npm dependency lock-in.
- **Accessible Design Systems with Tailwind CSS & Radix UI**: Fully accessible WAI-ARIA primitives styled with Tailwind.
- **Next.js & Vite Modern Web Applications**: Building polished SaaS dashboards and web interfaces.
- **Themable Component Libraries**: Customizing CSS variables, radius, and neutral color palettes.

## Quick Start

```bash
# Initialize shadcn in your Next.js / Vite project
npx shadcn@latest init

# Add components
npx shadcn@latest add button card dialog
```

```tsx
import { Button } from "@/components/ui/button";

export default function Demo() {
  return (
    <Button variant="outline" size="lg">
      shadcn Button
    </Button>
  );
}
```

## Core Concepts

### Composable Dialog Primitive with Radix UI

Accessible modal dialogs adhering to open standards:

```tsx
import * as React from "react";
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
  DialogFooter,
} from "@/components/ui/dialog";
import { Button } from "@/components/ui/button";

export function ConfirmActionModal() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="destructive">Delete Account</Button>
      </DialogTrigger>
      <DialogContent className="sm:max-w-[425px]">
        <DialogHeader>
          <DialogTitle>Are you absolutely sure?</DialogTitle>
          <DialogDescription>
            This action cannot be undone. This will permanently delete your
            account and remove your data.
          </DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <Button variant="outline">Cancel</Button>
          <Button variant="destructive">Confirm Deletion</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}
```

### Type-Safe Forms with React Hook Form & Zod

Form validation with accessible field bindings:

```tsx
"use client";

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import * as z from "zod";
import {
  Form,
  FormControl,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from "@/components/ui/form";
import { Input } from "@/components/ui/input";
import { Button } from "@/components/ui/button";

const formSchema = z.object({
  email: z.string().email("Invalid email format"),
});

export function SubscribeForm() {
  const form = useForm<z.infer<typeof formSchema>>({
    resolver: zodResolver(formSchema),
    defaultValues: { email: "" },
  });

  function onSubmit(values: z.infer<typeof formSchema>) {
    console.log("Submitted:", values);
  }

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
        <FormField
          control={form.control}
          name="email"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Email Address</FormLabel>
              <FormControl>
                <Input placeholder="you@domain.com" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />
        <Button type="submit">Subscribe</Button>
      </form>
    </Form>
  );
}
```

### Component Styling with cn() & class-variance-authority (cva)

Customizing variants with merge utility:

```tsx
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";

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

export function Badge({
  className,
  variant,
  ...props
}: React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof badgeVariants>) {
  return (
    <div className={cn(badgeVariants({ variant }), className)} {...props} />
  );
}
```

## Common Patterns

### Composed Dialog with Form Validation

**Problem**: Creating modal forms with focus trap, backdrop dismissal, and accessible keyboard navigation.

**Solution**:
Compose Radix Dialog with Tailwind classes:

```tsx
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
import { Button } from "@/components/ui/button";

export function ConfirmModal() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="destructive">Delete Item</Button>
      </DialogTrigger>
      <DialogContent className="sm:max-w-[425px]">
        <DialogHeader>
          <DialogTitle>Are you absolutely sure?</DialogTitle>
          <DialogDescription>
            This action cannot be undone. This will permanently delete your
            account.
          </DialogDescription>
        </DialogHeader>
        <div className="flex justify-end gap-3 mt-4">
          <Button variant="outline">Cancel</Button>
          <Button variant="destructive">Confirm Delete</Button>
        </div>
      </DialogContent>
    </Dialog>
  );
}
```

## Best Practices

**Do**:

- Install components on demand using the CLI (`npx shadcn@latest add button`) rather than copying everything at once.
- Use the `cn()` utility (`clsx` + `tailwind-merge`) to safely merge custom class names with defaults.
- Use `asChild` prop on triggers to avoid rendering invalid nested interactive HTML elements (e.g. button inside button).
- Define theme tokens in `globals.css` with HSL / OKLCH CSS variables for easy dark mode adaptation.

**Don't**:

- Treat `@/components/ui` as an external third-party library; feel free to modify components directly.
- Bypass Radix accessibility primitives for complex interactive components like dropdowns and dialogs.
- Remove ARIA attributes or focus styling from components.

## Troubleshooting

| Error                                         | Cause                                                | Solution                                                                                  |
| :-------------------------------------------- | :--------------------------------------------------- | :---------------------------------------------------------------------------------------- |
| `Cannot find module '@/components/ui/button'` | Path alias `@/*` not configured in `tsconfig.json`.  | Add `"paths": { "@/*": ["./src/*"] }` to `compilerOptions` in tsconfig.                   |
| `Styles missing / components appear unstyled` | Tailwind CSS not scanning component directory.       | Add `"./src/components/**/*.{js,ts,jsx,tsx}"` to `content` array in `tailwind.config.js`. |
| `Tailwind merge error: clsx is not defined`   | Missing `clsx` or `tailwind-merge` utility packages. | Run `npm install clsx tailwind-merge`.                                                    |

## References

- [shadcn/ui Documentation](https://ui.shadcn.com/)


---
Source attribution: G1Joshi
Original project: https://github.com/G1Joshi/Agent-Skills/blob/6a74cf03a8a86dc7d993ead3091b41123dbd0181/skills/frameworks/shadcnui/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 G1Joshi

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: G1Joshi
Original project: https://github.com/G1Joshi/Agent-Skills/blob/6a74cf03a8a86dc7d993ead3091b41123dbd0181/skills/frameworks/shadcnui/SKILL.md
Attribution basis: Source repository record

Fields of work: Design, Development & Engineering
Roles: Frontend Developer, Product Designer, UX Designer
Specialties: API, Cross Platform, Frontend
Tools: Radix Ui, Tailwind Css
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 65a0e2e17c20d66426585d0432d7c4617f6209c9060e4f5c1facf939de40aab0