{
/** Optional icon component */
icon?: React.ReactNode
}
export function Alert({ className, variant = "default", icon, children, ...props }: AlertProps) {
return (
{icon && {icon}}
{children}
)
}
```
Compared to the [`button.tsx`](https://github.com/shadcn-ui/ui/blob/main/button.tsx) implementation, this example defines only a `variant` dimension (no `size`), uses a simpler base class string appropriate for alerts, and accepts an optional `icon` prop for flexibility.
### Consuming Your Custom Component
Import and use your component exactly like any other shadcn component:
```tsx
import { Alert } from "@/registry/custom/ui/alert"
import { X } from "lucide-react"
export function Demo() {
return (
}>
Something went terribly wrong.
)
}
```
Because the component uses `cn` internally, any additional `className` you pass merges cleanly without duplicate utilities:
```tsx
```
### Extending Existing Variant Sets
When you need a new size or variant for an existing component (like `Button`), re-export the original `cva` instance and append your custom variants:
```tsx
// apps/v4/registry/custom/ui/button-extended.tsx
import { buttonVariants as baseButtonVariants } from "@/registry/new-york-v4/ui/button"
import { cva } from "class-variance-authority"
const buttonVariants = cva(baseButtonVariants, {
variants: {
size: {
...baseButtonVariants?.options?.variants?.size,
xl: "h-12 px-8 text-lg",
},
},
})
export { buttonVariants }
```
This approach preserves the original variant definitions while adding an `xl` size option. Any component that imports `buttonVariants` from this extended file will recognize the new size without duplicating the entire variant map.
## Practical Tips for the shadcn Style System
| Situation | Recommended Approach |
|-----------|----------------------|
| **Add a brand-specific color** | Extend Tailwind’s color palette in `tailwind.config.cjs`, then reference the new token inside a `cva` variant (e.g., `bg-brand-primary`). |
| **Create a shared layout component** | Keep it in `registry/shared/ui/…` so every app can import it via the alias `@/registry/shared/ui/...`. |
| **Override a component for a single project** | Duplicate the component file in your app’s `src/components/…`, import the original `cva` for consistency, and adjust only the variant map you need. |
| **Debug generated class strings** | Log `buttonVariants({ variant, size })` in the component; the output will be a plain string you can copy-paste into browser dev-tools to verify the Tailwind utilities. |
## Key Files to Explore in the shadcn-ui Repository
| File | Role | Link |
|------|------|------|
| [`apps/v4/lib/utils.ts`](https://github.com/shadcn-ui/ui/blob/main/apps/v4/lib/utils.ts) – `cn` helper | Merges class strings safely | |
| [`apps/v4/registry/new-york-v4/ui/button.tsx`](https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry/new-york-v4/ui/button.tsx) – Button implementation | Shows a full `cva` + `cn` pattern | |
| [`templates/monorepo-next/packages/ui/src/lib/utils.ts`](https://github.com/shadcn-ui/ui/blob/main/templates/monorepo-next/packages/ui/src/lib/utils.ts) – Alternative `cn` definition (used in templates) | Same utility in a different workspace | |
| `deprecated/www/tailwind.config.cjs` – Registry Tailwind config | Demonstrates how the registry is added to Tailwind’s `content` | |
| [`packages/shadcn/src/utils/templates.ts`](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/utils/templates.ts) – Component scaffolding logic | Generates component files for the CLI, helpful to see the intended structure | |
| [`apps/v4/registry/new-york-v4/lib/utils.ts`](https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry/new-york-v4/lib/utils.ts) – Same `cn` in the V4 app | Shows the alias resolution (`@/lib/utils`) | |
## Summary
- **Tailwind CSS** provides the design tokens and scans the `registry` folder for utility classes.
- **`cva`** (class-variance-authority) encapsulates component-level variants in a type-safe map, separating base styles from variant-specific overrides.
- **`cn`** combines `clsx` and `tailwind-merge` to merge generated classes with user-supplied `className` props while eliminating duplicates and resolving Tailwind conflicts.
- To **create custom styles**, add a new component file under the registry, define a `cva` map for your variants, and export a component that uses `cn` to merge classes.
- **Extend existing components** by re-importing their base `cva` instances and appending new variants, preserving the original design system while adding bespoke options.
## Frequently Asked Questions
### What is the difference between `cva` and `cn` in the shadcn style system?
`cva` (class-variance-authority) is responsible for defining and generating variant-based class strings according to a schema you define (e.g., mapping `variant="destructive"` to specific background and text colors). `cn` is a runtime utility that merges arbitrary class strings—including the output of `cva`—while removing duplicates and resolving Tailwind CSS conflicts using `tailwind-merge`. You typically call `cn(buttonVariants({ variant }), className)` to combine generated variants with user overrides.
### How do I add a new color token to the shadcn style system?
Extend your `tailwind.config.cjs` (or [`tailwind.config.ts`](https://github.com/shadcn-ui/ui/blob/main/tailwind.config.ts)) to include the new color in the theme extension, then reference it inside your `cva` variant definitions. For example, add `brand: { primary: "#3b82f6" }` to `theme.extend.colors`, then use `bg-brand-primary` or `text-brand-primary` within your component’s `cva` map. Because the registry folder is included in Tailwind’s `content` array, any new utilities will be automatically generated.
### Can I override shadcn component styles without forking the repository?
Yes. Copy the component file (e.g., [`button.tsx`](https://github.com/shadcn-ui/ui/blob/main/button.tsx)) from the registry into your application’s local component directory (e.g., [`src/components/ui/button.tsx`](https://github.com/shadcn-ui/ui/blob/main/src/components/ui/button.tsx)), then modify the `cva` variant map or the component logic directly. Import the original `cva` definition if you only need to add variants rather than replace them. Because shadcn components are installed directly into your codebase—not consumed as a npm package—you maintain full control over styling without maintaining a fork.
### Where should I place custom components in a shadcn project?
Place custom components under the registry path used by your application, typically `apps/v4/registry/[theme]/ui/` for the v4 application or `registry/` in older structures. This ensures Tailwind’s JIT engine scans your files for utility classes. Use path aliases (e.g., `@/registry/custom/ui/alert`) to import components consistently across your application. If you are working in a monorepo, consider a shared registry folder (e.g., `registry/shared/ui/`) that multiple applications can reference.