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 - Basic variants, boolean states, default values, required variants
• examples/compound-variants.md - Multi-condition styles, array syntax, state combinations
• examples/composition.md - VariantProps, class merging, multi-part components, extending variants
• 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 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 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 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"> &
  Required<Pick<BadgeVariants, "color">>;

See examples/composition.md for complete type extraction and required variant patterns.

---

Pattern 5: Class Merging with cx()

Use

cx()

(built-in, alias for clsx) for class concatenation. Use an external merge utility for class conflict resolution.

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

// cx() concatenates and filters falsy values
cx(buttonVariants({ intent: "primary" }), highlighted && "ring-2", className);

// For conflict resolution (e.g., caller overriding variant padding),
// use a class-merging utility wrapper
function button(variants: ButtonVariants, className?: string): string {
  return cn(buttonVariants(variants), className); // cn() resolves conflicts
}

See examples/composition.md for class merging patterns and conflict resolution.

---

Pattern 6: Multi-Part Components

Define separate cva for each styled part of a component (label, input, helper text). Share variant values for visual consistency.

const formFieldVariants = {
  label: cva(["block", "font-medium"], {
    variants: { size: { sm: ["text-sm"], md: ["text-base"] } },
    defaultVariants: { size: "md" },
  }),
  input: cva(["w-full", "border", "rounded"], {
    variants: {
      size: { sm: ["text-sm", "px-2"], md: ["text-base", "px-3"] },
      error: { false: ["border-gray-300"], true: ["border-red-500"] },
    },
    defaultVariants: { size: "md", error: false },
  }),
  helper: cva(["mt-1"], {
    variants: {
      size: { sm: ["text-xs"], md: ["text-sm"] },
      error: { false: ["text-gray-500"], true: ["text-red-600"] },
    },
    defaultVariants: { size: "md", error: false },
  }),
};

See examples/composition.md for multi-part and extending/composing variant patterns.

---

Pattern 7: Composing and Extending Variants

Combine multiple cva definitions with

cx()

for shared base + specialized variants.

const interactiveVariants = cva(["transition-colors", "focus:ring-2"], {
  variants: { focusRing: { blue: ["focus:ring-blue-500"] } },
  defaultVariants: { focusRing: "blue" },
});

const buttonVariants = cva(["font-semibold", "rounded"], {
  variants: { intent: { primary: ["bg-blue-600"] } },
  defaultVariants: { intent: "primary" },
});

// Compose with cx()
type ButtonProps = VariantProps<typeof interactiveVariants> &
  VariantProps<typeof buttonVariants>;

function button(props: ButtonProps): string {
  return cx(
    interactiveVariants({ focusRing: props.focusRing }),
    buttonVariants({ intent: props.intent }),
  );
}

See examples/composition.md for composition and extension patterns.

</patterns>

---

<red_flags>

RED FLAGS

High Priority Issues:

• Manual variant type definitions -- Types drift from cva definition, defeating type safety. Always use

  VariantProps<typeof variants>

  .
• Conditional class logic outside cva -- Defeats purpose of centralized variant definitions. Add the condition as a variant.
• Missing

  defaultVariants

  -- Calling without props returns incomplete classes. Always set defaults.
• Nested ternaries for combined states -- Use

  compoundVariants

  instead.
• Only defining

  true

  for boolean variants --

  false

  case should provide base/normal styles.

Medium Priority Issues:

• Space-separated class strings instead of arrays -- arrays are more readable and maintainable
• Not using

  cx()

  for class merging -- manual concatenation is error-prone
• Duplicating variant styles across components -- compose from shared base variants
• Putting complex responsive logic in cva -- keep cva simple, handle responsiveness in CSS

Gotchas & Edge Cases:

• VariantProps

  makes all variants optional (nullable) -- use TypeScript utilities (

  Required<Pick<>>

  ) to make specific ones required

• compoundVariants

  are applied AFTER regular variants -- order matters for class specificity
• Empty variant values (

  null

  or empty string) are valid -- useful for "no additional styles" case
• Base classes are always applied -- you cannot conditionally remove them via variants
• Both

  class

  and

  className

  work in

  compoundVariants

  config -- pick one and be consistent (

  class

  in non-React contexts,

  className

  if you prefer React conventions)
• Don't forget

  import type

  for

  VariantProps

  :

  import { cva, type VariantProps }

</red_flags>

---

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md

(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)

Failure to follow these rules will break type safety, create inconsistent styling, and defeat the purpose of using CVA.

</critical_reminders>