shadcn-syntax-variant-cva

name	shadcn-syntax-variant-cva
description	Use when defining or modifying variants on a shadcn ui component, writing a new component that needs `variant` / `size` props, extending the Button with a custom variant, debugging why a `className` override is not winning, or inferring TypeScript props from a `cva()` call. Prevents the common mistakes : concatenating Tailwind class strings with `+ " "` instead of `cn()`, forgetting `tailwind-merge` so duplicate utilities leak through, mis-ordering `compoundVariants` so the override loses to the default, omitting `VariantProps` so consumers cannot extend the component type, and re-implementing variant logic with hand-written `if`-branches that destroy type inference. Covers the full `cva(base, config)` signature (base as string or string array, `variants`, `compoundVariants`, `defaultVariants`), the `VariantProps<typeof X>` inference pattern, the canonical `cn(...inputs)` helper composition of `clsx` plus `twMerge`, the evaluation order (default then variant then compound), and the Radix `Slot` (`asChild`) polymorphic-rendering pattern. Code examples are version-explicit for Tailwind v3 versus Tailwind v4. Keywords: cva, class-variance-authority, VariantProps, cn helper, twMerge, tailwind-merge, clsx, compoundVariants, defaultVariants, variants, Slot, asChild, polymorphic component, buttonVariants, variant not applying, className override not working, duplicate tailwind classes, classes not merging, how do I add a variant, what is cva, how does VariantProps work, why is className ignored, why are my Tailwind classes duplicated, type-safe variants, Radix Slot.
license	MIT
compatibility	Designed for Claude Code. Requires shadcn ui evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

shadcn ui : Variant API with cva

shadcn components express their visual variants through class-variance-authority (cva). The single most common source of styling bugs in a shadcn project is misuse of cva or its companion helper cn(). ALWAYS internalise this skill before adding, editing, or reviewing a variants object.

Quick Reference

cva in three lines

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

const buttonVariants = cva("inline-flex items-center", {
  variants: { variant: { default: "bg-primary", outline: "border" } },
  defaultVariants: { variant: "default" },
})

Three rules apply to every cva call :

1. ALWAYS pass the result of buttonVariants({ ... }) through cn(...) together with any caller className. NEVER return the raw cva() output to the DOM.
2. ALWAYS export VariantProps<typeof buttonVariants> (directly or via a Props type) so consumers can extend the component. NEVER hand-roll the variant union by typing strings.
3. ALWAYS list variant values as quoted string keys (outline: "..."), never raw booleans or numbers as keys ; cva treats keys as strings under the hood and TypeScript inference relies on it.

Canonical Button pattern (verbatim from shadcn registry, Tailwind v4)

import * as React from "react"
import { cva, type  }  
 {  }  
 { cn }  

 buttonVariants = (
  ,
  {
    : {
      : {
        : ,
        : ,
        : ,
        : ,
      },
      : {
        : ,
        : ,
        : ,
        : ,
      },
    },
    : { : , :  },
  }
)

 () {
    = asChild ? . : 
   (
    
  )
}

 { , buttonVariants }