web-styling-cva

CVA (Class Variance Authority) Patterns

Quick Guide: Use CVA to define type-safe component variants with a declarative API. Define base classes, variant groups (size, intent, state), compound variants for combined conditions, and default values. Extract types with VariantProps. Works with any CSS approach (utility classes, CSS modules, plain CSS). Always set defaultVariants, always define both true/false for boolean variants, always use VariantProps for type extraction.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST define all variant options in the variants object - NEVER use conditional class logic outside cva)

(You MUST use VariantProps to extract types - NEVER manually define variant prop types)

(You MUST use defaultVariants for initial state - NEVER rely on undefined props for defaults)

(You MUST use compoundVariants for multi-condition styles - NEVER nest ternaries for combined states)

</critical_requirements>

Auto-detection: cva, class-variance-authority, VariantProps, variants, compoundVariants, defaultVariants, component variants, type-safe styling, cx

When to use:

• Building components with multiple visual variants (size, intent, state)
• Creating design system components with type-safe props
• Implementing compound conditions (e.g., "large primary" has special styles)
• Sharing variant styling across projects or frameworks

When NOT to use:

• Simple components with no variants (just use plain classes)
• One-off styling without pattern reuse
• Dynamic styles based on runtime values (use inline styles or CSS variables)
• Responsive styles that change based on viewport (use CSS media queries)

Key patterns covered:

• Basic variant definitions with cva()
• Boolean variants for toggle states
• Compound variants for combined conditions
• Type extraction with VariantProps
• Class merging with cx() and external utilities
• Multi-part component patterns
• Composing and extending variant definitions

Detailed Resources:

• [examples/core.md](examples/core.md) - Basic variants, boolean states, default values, required variants
• [examples/compound-variants.md](examples/compound-variants.md) - Multi-condition styles, array syntax, state combinations
• [examples/composition.md](examples/composition.md) - VariantProps, class merging, multi-part components, extending variants
• [reference.md](reference.md) - Decision frameworks, anti-patterns, quick reference

<philosophy>

Philosophy

CVA treats component variants as a type system for UI states. Instead of scattering conditional class logic throughout components, CVA centralizes variant definitions in a single, typed configuration object.

Core Principles:

• Declarative over imperative: Define what each variant looks like, not how to compute classes
• Type-safe variants: TypeScript catches invalid variant values at compile time
• Framework-agnostic: Works with any UI framework and any CSS approach
• Composition-friendly: Variants can be combined, extended, and composed
• Single source of truth: Variant definitions live in one place, types are derived

Why CVA over manual conditional classes:

// BAD: scattered logic, no type safety, hard to maintain
function getButtonClasses(size: string, variant: string, disabled: boolean) {
  let classes = "btn";
  if (size === "sm") classes += " btn-sm";
  else if (size === "lg") classes += " btn-lg";
  if (variant === "primary") classes += " btn-primary";
  if (disabled) classes += " btn-disabled";
  return classes;
}

// GOOD: declarative, type-safe, composable
const buttonVariants = cva("btn", {
  variants: {
    size: { sm: "btn-sm", lg: "btn-lg" },
    variant: { primary: "btn-primary" },
    disabled: { true: "btn-disabled" },
  },
});

</philosophy>

<patterns>

Core Patterns

Pattern 1: Basic Variant Definition

Define component styles with base classes and variant options. Use array syntax for readability, always set defaultVariants.

import { cva } from "class-variance-authority";

const buttonVariants = cva(
  ["font-semibold", "border", "rounded"], // base classes as array
  {
    variants: {
      intent: {
        primary: ["bg-blue-600", "text-white"],
        secondary: ["bg-white", "text-gray-800"],
      },
      size: {
        sm: ["text-sm", "py-1", "px-2"],
        md: ["text-base", "py-2", "px-4"],
      },
    },
    defaultVariants: {
      intent: "primary",
      size: "md",
    },
  },
);

buttonVariants(); // defaults: primary + md
buttonVariants({ intent: "secondary" }); // secondary + md

Key rules: always provide defaultVariants (calling without props returns incomplete classes otherwise), use arrays over space-separated strings for readability.

See [examples/core.md](examples/core.md) for complete button, badge, and icon button examples.

Pattern 2: Boolean Variants

Use true/false keys for binary states. Always define both sides.

const inputVariants = cva(["border", "rounded", "px-3", "py-2"], {
  variants: {
    disabled: {
      false: ["bg-white", "cursor-text"], // normal state
      true: ["bg-gray-100", "cursor-not-allowed"], // disabled state
    },
    error: {
      false: ["border-gray-300"],
      true: ["border-red-500"],
    },
  },
  defaultVariants: { disabled: false, error: false },
});

Key rule: missing false case means no styles applied in normal state -- variant logic becomes incomplete.

See [examples/core.md](examples/core.md) for boolean variant patterns with loading, disabled, and error states.

Pattern 3: Compound Variants

Use compoundVariants when specific variant combinations need special styles. Array syntax matches multiple values.

const buttonVariants = cva(["font-semibold", "rounded"], {
  variants: {
    intent: {
      primary: ["bg-blue-600", "text-white"],
      secondary: ["bg-white", "text-gray-800"],
    },
    disabled: {
      false: null,
      true: ["opacity-50", "cursor-not-allowed"],
    },
  },
  compoundVariants: [
    // Hover only when enabled
    { intent: "primary", disabled: false, class: ["hover:bg-blue-700"] },
    { intent: "secondary", disabled: false, class: ["hover:bg-gray-100"] },
    // Array syntax: matches multiple values
    {
      intent: ["primary", "secondary"],
      disabled: true,
      class: ["pointer-events-none"],
    },
  ],
  defaultVariants: { intent: "primary", disabled: false },
});

Key rules: compound variants express "when X AND Y, also apply Z", array syntax avoids duplicating rules across similar variants.

See [examples/compound-variants.md](examples/compound-variants.md) for hover states, loading overrides, state matrices, and multi-part compounds.

Pattern 4: Type Extraction with VariantProps

Always use VariantProps to extract types from cva definitions -- never manually define variant types.

import { cva, type VariantProps } from "class-variance-authority";

const cardVariants = cva(["rounded-lg", "border"], {
  variants: {
    elevation: { flat: ["shadow-none"], raised: ["shadow-md"] },
    padding: { none: ["p-0"], sm: ["p-2"], md: ["p-4"] },
  },
  defaultVariants: { elevation: "flat", padding: "md" },
});

// Extract types -- always in sync with cva definition
type CardVariants = VariantProps<typeof cardVariants>;
// { elevation?: "flat" | "raised" | null; padding?: "none" | "sm" | "md" | null }

interface CardProps extends CardVariants {
  children: unknown;
  className?: string;
}

Key rule: manual types drift when you add/remove variants. VariantProps is always in sync.

To make specific variants required (no default):

type BadgeProps = Omit<BadgeVariants, "color">