What's New?

---

What’s changed since class-variance-authority@0.*?

Features

1. defineConfig

Extend cva via the new defineConfig API.

Use cva/cx with tailwind-merge via the new hooks.onComplete option.

2. composes

Shallow merge one or more cva components into a single component via the new composes property.

This replaces the compose function.

3. getSchema

Extract a plain-object schema (variant names, values and defaults) from a cva component via the new getSchema utility. Use it to generate Storybook controls or any other UI that reads a component’s variants.

4. Internal variants

A variant name prefixed with _ is now internal: hidden from the component’s props type and from getSchema, while still settable via defaultVariants and matchable in compoundVariants.

Breaking change

If a component already declared a variant with a leading underscore (_state, _internal, etc.), that variant now disappears from its prop types and from getSchema results. It still resolves at runtime through defaultVariants or a matching compoundVariants entry, so rename it if your code relied on setting it as a public prop.

Deprecations

1. compose → composes

The compose method is deprecated in favor of the composes property inside cva. Pass a single component directly, or pass multiple components as an array.

import { cva, compose } from "cva";
import { cva } from "cva";

const box = cva({ /* ... */ });
const root = cva({ /* ... */ });

const card = compose(box, root);
const card = cva({ composes: [box, root] });

Note

composes isn’t always a byte-for-byte swap. When composed components declare conflicting defaultVariants for the same key, composes applies a single last-wins default to every component. compose let each component resolve its own default instead. See Extending variants.

See Composing Components for more details and migration examples.

Enhancements

1. class-variance-authority → cva

One of the biggest (and let’s be honest, most important) complaints about class-variance-authority was that the name was just too damn long.

Shout-out to GitHub for transferring npm ownership of cva!

2. cva now accepts a single parameter

Base styles are now applied via the named base property.

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

const component = cva({ base: "your-base-class" });

3. Goodbye null

Previously, passing null to a variant would disable it completely, to match the behavior of Stitches.js. However, this caused a great deal of confusion.

Instead, we now recommend explicitly rolling your own unset variant.

4. Clearer type guards

cva uses generic type parameters to infer variant types. Some users mistook these for a customization option.

If you now pass a generic type parameter, cva throws an error.