Skip to main content

Get started

Install CVA and build your first variant component in minutes.

API Reference

Explore the full API — cva, cx, compose, and defineConfig.

Core Concepts

Learn variants, compound variants, default variants, and composition.

Examples

See CVA in action with React, Vue, Svelte, Astro, and more.

​
What is CVA?

Class Variance Authority (cva) is a tiny (~1.6KB) TypeScript utility for creating type-safe component variants. Instead of juggling conditional class strings by hand, you declare your variants declaratively and let CVA handle the logic. 
import { cva } from "class-variance-authority";

const button = cva("font-semibold border rounded", {
  variants: {
    intent: {
      primary: "bg-blue-500 text-white border-transparent",
      secondary: "bg-white text-gray-800 border-gray-400",
    },
    size: {
      small: "text-sm py-1 px-2",
      medium: "text-base py-2 px-4",
    },
  },
  defaultVariants: {
    intent: "primary",
    size: "medium",
  },
});

button({ intent: "secondary", size: "small" });
// => "font-semibold border rounded bg-white text-gray-800 border-gray-400 text-sm py-1 px-2"

​
Why CVA?

Type-safe variants

Full TypeScript inference — autocomplete for every variant value, and compile-time errors for invalid combinations.

Framework-agnostic

Works anywhere CSS class names work — React, Vue, Svelte, Astro, plain HTML, and more.

Tiny footprint

Under 1.6KB minzipped. No runtime overhead — just string concatenation done right.

Composable

Combine multiple CVA components together with compose and cx.

​
Key features

  • Variants — define visual or behavioral variants (size, intent, state) as named keys with class values
  • Compound variants — apply classes only when multiple variant conditions are met simultaneously
  • Default variants — set sensible fallback values so callers don’t have to pass every prop
  • cx utility — a re-exported clsx alias for merging arbitrary class names
  • compose — merge the variant props of multiple CVA components into one function
  • defineConfig — create a custom instance with an onComplete hook (e.g. to run tailwind-merge on every output)

​
Quick install

npm install class-variance-authority
From v1 onwards the package is also published as cva. During the beta period use class-variance-authority or alias it — see the installation guide for details.

Build docs developers (and LLMs) love

Get started for freeTalk to us