Skip to content

Migrating from class-variance-authority

The concepts are the same, so most recipes move over with a few mechanical changes. The two libraries can live side by side in one app, so you can migrate one component at a time (see Migrating a large codebase). For a shadcn/ui project, see also Using with shadcn/ui.

class-variance-authority class-recipe
cva(base, config) cva({ base, ...config })
cva(base), without variants cva({ base, variants: {} }), since variants is required
Arrays or objects of classes One string wherever the config takes classes; cx(...) turns an array or an object into one
An option whose classes are null An option whose classes are ""
A compound variant { intent: "primary", class: "..." }, or with className { variants: { intent: "primary" }, className: "..." }, as in Compound variants and the class prop
class or className prop className prop, which takes one string and ignores any other value; cx(...) turns an array or an object into one
VariantProps<typeof button> VariantsOf<typeof button>, from @lynstack/class-recipe, in which a required variant stays required
twMerge(button(props)) cva from createRecipes({ join: twMerge })
A cn helper, twMerge(clsx(...)) cx from createRecipes({ join: twMerge })
cn, imported from "cn" cx from createRecipes({ join: cn })
cx, which is clsx cx
Beforeclass-variance-authority0.7.1
import { cva } from "class-variance-authority";
export const button = cva("rounded-md font-medium", {
variants: {
intent: { primary: "bg-blue-600 text-white", secondary: "bg-gray-100" },
size: { sm: "h-8 px-3", md: "h-10 px-4" },
},
compoundVariants: [{ intent: "primary", size: "md", class: "shadow-sm" }],
defaultVariants: { intent: "primary", size: "md" },
});
Afterclass-recipe1.7.3
import { cva } from "@lynstack/class-recipe";
export const button = cva({
base: "rounded-md font-medium",
variants: {
intent: { primary: "bg-blue-600 text-white", secondary: "bg-gray-100" },
size: { sm: "h-8 px-3", md: "h-10 px-4" },
},
compoundVariants: [
{ variants: { intent: "primary", size: "md" }, className: "shadow-sm" },
],
defaultVariants: { intent: "primary", size: "md" },
});

class-variance-authority keeps every class, as class-recipe does by default. To merge classes with tailwind-merge, as twMerge(button(props)) or a cn helper does, create the functions with createRecipes once, as Merging classes shows. The cx it returns replaces a cn helper: it joins its inputs as clsx does, then merges them. To keep the imports of your components, export the functions from the module that held your helper, such as src/lib/utils.ts; see Using with shadcn/ui.

A recipe created with the join merges the classes of every call, including a call whose result was not passed to cn before. A component that passes a recipe call to cn passes its other classes as className instead, which the recipe adds last and merges with the join:

  • cn(buttonVariants({ variant, size, className })) becomes buttonVariants({ variant, size, className }).
  • cn(buttonVariants({ variant, size }), "w-full", className) becomes buttonVariants({ variant, size, className: cn("w-full", className) }).

Keeping the cn call gives the same classes, but runs the join on every call, where a recipe call without className reads the cache (see What it costs).

A compound variant of class-recipe puts its condition under variants, and its classes under className. A recipe takes its override as className, never class. TypeScript reports the shapes of class-variance-authority as errors:

const button = cva({
base: "rounded-md",
variants: { intent: { primary: "bg-blue-600", secondary: "bg-gray-100" } },
compoundVariants: [{ intent: "primary", class: "uppercase" }],
// Error: Object literal may only specify known properties, and 'intent'
// does not exist in type 'CompoundVariant<…>'.
});
button({ intent: "primary", class: "w-full" });
// Error: Object literal may only specify known properties, and 'class'
// does not exist in type '…'.

The error names the type CompoundVariant, the type of an entry of compoundVariants, and points at the first property that it does not know. Move the condition under variants, and rename class to className.

In JavaScript, or in a config that bypasses the types, creating the recipe throws a TypeError that names the compound variant: one without variants, or one with class, which it asks you to rename to className.

A class prop is part of a call, not of the config, so nothing reports it in JavaScript: the recipe ignores it. To find class props, search the calls of your recipes for class:.

Each example below calls the recipe before and after the migration, and shows what it returns.

A variant without a default becomes required

Section titled “A variant without a default becomes required”

A variant without a default must be passed, unless it is a boolean variant, whose only options are true, false, or both: every call that omits it is a type error. Give it a default. To add no classes when it is omitted, as class-variance-authority does, default to an option without classes:

Beforeclass-variance-authority0.7.1
import { cva } from "class-variance-authority";
export const badge = cva("rounded px-2", {
variants: {
tone: { info: "bg-blue-100", danger: "bg-red-100" },
},
});
badge()→ "rounded px-2"badge({ tone: "danger" })→ "rounded px-2 bg-red-100"
Afterclass-recipe1.7.3
import { cva } from "@lynstack/class-recipe";
export const badge = cva({
base: "rounded px-2",
variants: {
tone: { none: "", info: "bg-blue-100", danger: "bg-red-100" },
},
defaultVariants: { tone: "none" },
});
badge()→ "rounded px-2"badge({ tone: "danger" })→ "rounded px-2 bg-red-100"

Give the new option a name that the variant does not use yet, such as none or unset; it becomes a value that the props of a component accept. An option without classes that the variant declares already works too, unless a compound variant names it, since the condition would then match calls that omit the variant.

If every caller already passes the variant, such as a component that destructures the prop with a default, make that value the default of the recipe instead. Keep the component’s default as well if it reads the prop for anything else, such as a data-variant attribute.

When a call omits a boolean variant without a default, class-recipe adds the classes of its false option, and a compound condition on false matches. class-variance-authority adds no classes for it:

Beforeclass-variance-authority0.7.1
import { cva } from "class-variance-authority";
export const input = cva("rounded border", {
variants: {
disabled: { true: "opacity-50", false: "cursor-text" },
},
compoundVariants: [{ disabled: false, class: "bg-white" }],
});
input()→ "rounded border"Differsinput({ disabled: false })→ "rounded border cursor-text bg-white"
Afterclass-recipe1.7.3
import { cva } from "@lynstack/class-recipe";
export const input = cva({
base: "rounded border",
variants: {
disabled: { true: "opacity-50", false: "cursor-text" },
},
compoundVariants: [{ variants: { disabled: false }, className: "bg-white" }],
});
input()→ "rounded border cursor-text bg-white"Differsinput({ disabled: false })→ "rounded border cursor-text bg-white"

To add no classes when a call omits it, as before, declare an option without classes and make it the default, such as disabled: { unset: "", true: "opacity-50", false: "cursor-text" } with defaultVariants: { disabled: "unset" }. The variant still accepts true and false.

class-variance-authority adds no classes for a variant passed as null, even one with a default. The types of class-recipe reject null, and a null from untyped data counts as an omitted prop. To let a component turn a variant off, declare an option without classes, and replace a compound condition on null with one on that option:

Beforeclass-variance-authority0.7.1
import { cva } from "class-variance-authority";
export const button = cva("rounded", {
variants: {
size: { sm: "h-8 px-3", md: "h-10 px-4" },
},
defaultVariants: { size: "md" },
});
button()→ "rounded h-10 px-4"button({ size: null })→ "rounded"
Afterclass-recipe1.7.3
import { cva } from "@lynstack/class-recipe";
export const button = cva({
base: "rounded",
variants: {
size: { none: "", sm: "h-8 px-3", md: "h-10 px-4" },
},
defaultVariants: { size: "md" },
});
button()→ "rounded h-10 px-4"button({ size: "none" })→ "rounded"

A compound condition on undefined matches any option

Section titled “A compound condition on undefined matches any option”

A condition on undefined matches any option, as a variant left out of the condition does. class-variance-authority matches it only when the prop is omitted and the variant has no default:

Beforeclass-variance-authority0.7.1
import { cva } from "class-variance-authority";
export const alert = cva("rounded p-4", {
variants: {
tone: { info: "bg-blue-50", danger: "bg-red-50" },
},
compoundVariants: [{ tone: undefined, class: "border" }],
defaultVariants: { tone: "info" },
});
alert()→ "rounded p-4 bg-blue-50"Differsalert({ tone: "danger" })→ "rounded p-4 bg-red-50"Differs
Afterclass-recipe1.7.3
import { cva } from "@lynstack/class-recipe";
export const alert = cva({
base: "rounded p-4",
variants: {
tone: { info: "bg-blue-50", danger: "bg-red-50" },
},
compoundVariants: [{ variants: { tone: undefined }, className: "border" }],
defaultVariants: { tone: "info" },
});
alert()→ "rounded p-4 bg-blue-50 border"Differsalert({ tone: "danger" })→ "rounded p-4 bg-red-50 border"Differs

For a variant without a default, name instead the option without classes that it now defaults to (see above). For a variant with a default, the condition never matched, so delete the compound variant.

A recipe without them is a type error, and throws a TypeError that says so when it is created. Pass variants: {}. class-variance-authority ignores the compound variants of a config without variants, so drop them.

The types of class-variance-authority reject the values below, so these changes reach only data that bypasses the types, such as the props of a JavaScript component or the values of a form. The calls in these examples pass such values.

An empty string adds no classes for the variant

Section titled “An empty string adds no classes for the variant”

class-variance-authority uses the default instead:

Beforeclass-variance-authority0.7.1
import { cva } from "class-variance-authority";
export const button = cva("rounded", {
variants: {
size: { sm: "h-8 px-3", md: "h-10 px-4" },
},
defaultVariants: { size: "md" },
});
button({ size: "" })→ "rounded h-10 px-4"Differs
Afterclass-recipe1.7.3
import { cva } from "@lynstack/class-recipe";
export const button = cva({
base: "rounded",
variants: {
size: { sm: "h-8 px-3", md: "h-10 px-4" },
},
defaultVariants: { size: "md" },
});
button({ size: "" })→ "rounded"Differs

A compound condition names only declared variants

Section titled “A compound condition names only declared variants”

class-variance-authority matches a condition on a prop that is not a variant when a call passes that prop, as a component that spreads its props into the recipe does. class-recipe never matches such a condition, and warns about it when the recipe is created. Declare the prop as a variant whose options add no classes, and the condition matches as before:

Beforeclass-variance-authority0.7.1
import { cva } from "class-variance-authority";
export const button = cva("px-4", {
variants: {
isInGroup: { true: "border-s-0" },
},
compoundVariants: [
{ isInGroup: true, isRounded: true, class: "shadow-sm" },
],
});
button({ isInGroup: true })→ "px-4 border-s-0"button({ isInGroup: true, isRounded: true })→ "px-4 border-s-0 shadow-sm"
Afterclass-recipe1.7.3
import { cva } from "@lynstack/class-recipe";
export const button = cva({
base: "px-4",
variants: {
isInGroup: { true: "border-s-0" },
isRounded: { true: "" },
},
compoundVariants: [
{ variants: { isInGroup: true, isRounded: true }, className: "shadow-sm" },
],
});
button({ isInGroup: true })→ "px-4 border-s-0"button({ isInGroup: true, isRounded: true })→ "px-4 border-s-0 shadow-sm"

A compound condition matches an option by its name

Section titled “A compound condition matches an option by its name”

A condition on true matches the prop "true", and one on 2 matches the prop "2", as the types of class-recipe allow. class-variance-authority compares the condition with the prop as it is, so it matches only the same type:

Beforeclass-variance-authority0.7.1
import { cva } from "class-variance-authority";
export const toggle = cva("rounded", {
variants: {
pressed: { true: "bg-gray-900", false: "bg-white" },
level: { 1: "text-sm", 2: "text-base" },
},
compoundVariants: [
{ pressed: true, class: "shadow-inner" },
{ level: 2, class: "font-medium" },
],
defaultVariants: { pressed: false, level: 1 },
});
toggle({ pressed: true })→ "rounded bg-gray-900 text-sm shadow-inner"toggle({ level: 2 })→ "rounded bg-white text-base font-medium"toggle({ pressed: "true" })→ "rounded bg-gray-900 text-sm"Differstoggle({ level: "2" })→ "rounded bg-white text-base"Differs
Afterclass-recipe1.7.3
import { cva } from "@lynstack/class-recipe";
export const toggle = cva({
base: "rounded",
variants: {
pressed: { true: "bg-gray-900", false: "bg-white" },
level: { 1: "text-sm", 2: "text-base" },
},
compoundVariants: [
{ variants: { pressed: true }, className: "shadow-inner" },
{ variants: { level: 2 }, className: "font-medium" },
],
defaultVariants: { pressed: false, level: 1 },
});
toggle({ pressed: true })→ "rounded bg-gray-900 text-sm shadow-inner"toggle({ level: 2 })→ "rounded bg-white text-base font-medium"toggle({ pressed: "true" })→ "rounded bg-gray-900 text-sm shadow-inner"Differstoggle({ level: "2" })→ "rounded bg-white text-base font-medium"Differs

class-variance-authority and class-recipe can run side by side: they are separate packages, and a component uses whichever one its recipe comes from. Migrate one component at a time:

  1. Install @lynstack/class-recipe. If your components pass recipe results to cn or twMerge, create the functions with createRecipes (see Merging classes).
  2. Pick a component. Rewrite its recipe with the table at the top of this page: one config object, variants even when empty, compound variants with variants and className, and strings instead of arrays.
  3. Give a default to each variant that callers may leave out, as A variant without a default becomes required shows.
  4. Replace VariantProps with VariantsOf, and class props with className.
  5. Run TypeScript. Each error points at a call that leaves out a required variant, or at a config shape that changed.
  6. Compare the old and the new recipe with the test below, then delete the old one.
  7. When no file imports class-variance-authority, uninstall it.

Keep the old recipe next to the new one while you migrate, and compare them on every selection. variantOptions lists the options of each variant, so the test can call both recipes with every combination:

button.test.ts
import { expect, test } from "vitest";
import { button } from "./button";
import { button as oldButton } from "./button.old";
type Selection = Record<string, string | boolean>;
/** Every selection of a recipe: one option of each variant. */
function selectionsOf(
variantOptions: Readonly<Record<string, readonly string[]>>,
): Selection[] {
return Object.entries(variantOptions).reduce<Selection[]>(
(selections, [variant, options]) =>
selections.flatMap((selection) =>
options.map((option) => ({ ...selection, [variant]: propOf(option) })),
),
[{}],
);
}
/** Passes "true" and "false" as booleans, as components do. */
function propOf(option: string): string | boolean {
if (option === "true" || option === "false") {
return option === "true";
}
return option;
}
/** The classes of a class name, in a stable order. */
function classesOf(className: string): string[] {
return className.split(" ").filter(Boolean).sort();
}
const callButton = button as (props: Selection) => string;
const callOldButton = oldButton as (props: Selection) => string;
test.each(selectionsOf(button.variantOptions))(
"button(%o) has the same classes as before",
(selection) => {
expect(classesOf(callButton(selection))).toEqual(
classesOf(callOldButton(selection)),
);
},
);

The test compares sets of classes, so a change in their order does not fail it. It passes every variant, so it does not test what a call that leaves one out returns; add such calls when a variant had no default before. An option name that is a number reaches both recipes as a string, so a compound condition of class-variance-authority on that number does not match it (see A compound condition matches an option by its name).