Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cva
✓ import { cva } from 'class-variance-authority';
✗ import cva from 'class-variance-authority';
import { cva } from 'cva';
The main utility function is a named export. While the `cva` package name exists, the actual library is published as `class-variance-authority` (as of v0.x). Using `import { cva } from 'cva'` will likely import the old, placeholder package.
VariantProps
✓ import { type VariantProps } from 'class-variance-authority';
✗ import { VariantProps } from 'class-variance-authority';
Use `type` import for `VariantProps` to ensure it's removed during compilation, as it's a TypeScript-only utility type.
* (CommonJS)
✓ const { cva } = require('class-variance-authority');
✗ const cva = require('class-variance-authority');
For CommonJS, `cva` is a named export from the module object. The primary package is `class-variance-authority`.
This quickstart demonstrates how to define component variants using `cva` with base classes, distinct variants, compound variants for specific combinations, and default values. It also shows how to extract a type-safe `ButtonProps` interface using `VariantProps` for use in a component's props.
import { cva, type VariantProps } from 'class-variance-authority';
const buttonVariants = cva(
'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none',
{
variants: {
intent: {
primary: 'bg-blue-600 text-white hover:bg-blue-700',
secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300',
danger: 'bg-red-500 text-white hover:bg-red-600',
},
size: {
sm: 'h-9 px-3 py-2',
md: 'h-10 px-4 py-2',
lg: 'h-11 px-6 py-3',
},
},
compoundVariants: [
{ intent: 'primary', size: 'md', class: 'uppercase' },
{ intent: 'secondary', size: 'sm', class: 'font-normal' }
],
defaultVariants: {
intent: 'primary',
size: 'md',
},
}
);
type ButtonProps = VariantProps<typeof buttonVariants>;
// Example usage:
console.log(buttonVariants({ intent: 'primary', size: 'lg' }));
// Expected output: 'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none bg-blue-600 text-white hover:bg-blue-700 h-11 px-6 py-3'
console.log(buttonVariants({ intent: 'secondary', size: 'sm' }));
// Expected output: 'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none bg-gray-200 text-gray-900 hover:bg-gray-300 h-9 px-3 py-2 font-normal'
console.log(buttonVariants({}));
// Expected output (default variants): 'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none bg-blue-600 text-white hover:bg-blue-700 h-10 px-4 py-2 uppercase'
Debug
Known issues
gotchaThe official package name for Class Variance Authority is `class-variance-authority`, not `cva`. The `cva` package on npm is an abandoned placeholder.fixAlways `npm install class-variance-authority` (or `yarn add class-variance-authority`). From v1, the package name `cva` is intended to become primary, but verify this in official documentation when upgrading.
affects: <=0.7.1
breakingFuture versions (specifically v1) are expected to transition the primary npm package name from `class-variance-authority` to `cva`. This will require updating import paths in your codebase.fixMonitor official CVA documentation and release notes for v1.0.0. When it ships, update your imports from `from 'class-variance-authority'` to `from 'cva'`.
affects: >=1.0.0 (expected)
gotchaWhen using TypeScript, always use `type` import for `VariantProps` to ensure it's stripped from the compiled output.fixChange `import { VariantProps } from 'class-variance-authority';` to `import { type VariantProps } from 'class-variance-authority';` affects: >=0.1.0
Errors
Common errors & fixes
Cannot find module 'cva' or its corresponding type declarations.
Attempting to import from the `cva` package name, which is a placeholder, instead of `class-variance-authority`.
fixEnsure you have installed `class-variance-authority` (`npm install class-variance-authority`) and your import statement is `import { cva } from 'class-variance-authority';`. Argument of type '{ variant: string; }' is not assignable to parameter of type 'VariantProps<typeof buttonVariants> | undefined'.
Passing an invalid variant value that is not defined in your `cva` configuration, or a typo in the variant name.
fixCheck your `cva` definition to ensure the variant name and its possible values match what you are passing. TypeScript helps catch these at compile time; ensure your editor shows the correct type suggestions.
Audit
Dependencies
clsxrequiredUsed internally for efficiently combining class names.