Skip to content

cva

cva creates a recipe, which returns the class name of one element for a selection of variants. It is also exported as createRecipe. For how variants work, read Variants first.

import { cva } from "@lynstack/class-recipe";
export const badge = cva({
// Applied whatever the variants.
base: "inline-flex rounded-full px-2 text-xs",
// For each variant, the classes of each option.
variants: {
tone: {
neutral: "bg-gray-100 text-gray-700",
success: "bg-green-100 text-green-800",
danger: "bg-red-100 text-red-800",
},
outlined: {
true: "ring-1 ring-inset ring-current",
},
},
});

PlaygroundChoose the variants. The classes a choice adds light up.

tone
outlined
badge({ tone: "neutral" })→ "inline-flex rounded-full px-2 text-xs bg-gray-100 text-gray-700"
import { cva } from "@lynstack/class-recipe";
const recipe = cva(config);
recipe(props); // => string

cva infers the types of the recipe from config: the names of the variants and options, and which variants are required. Its type is CreateRecipe (see All exports).

Property Required Description
variants Required For each variant name, the classes of each of its options, as a string. Pass variants: {} when the recipe has no variants. className and classNames are reserved.
base Optional The classes the element always has.
compoundVariants Optional A list of compound variants: classes added when several variants have particular options at the same time.
defaultVariants Optional The option each variant uses when a call leaves it out. A variant without a default is required.
composes Optional Recipes whose configs the recipe adds before its own; see Composing recipes.
cache Optional Whether the recipe caches its class names. Defaults to the cache option of createRecipes, which is true.

variants is required even when it is empty. A config without it is a type error. In JavaScript, or in a config that bypasses the types, creating the recipe throws a TypeError that names what is wrong: no variants, classes that are not a string, or a compound variant without variants or className.

A default or a compound variant can name a variant or an option that neither the config nor the recipes it composes declare, such as a misspelled one. TypeScript rejects such a name in a config written in the call. A config declared before the call can let some through (see A config declared before the call), and JavaScript checks none. The recipe adds no classes for such a name:

  • A default of an undeclared variant is ignored.
  • A default option that its variant does not declare selects no option, so a call that leaves the variant out adds no classes for it. The recipe’s defaultVariants still lists that option as written.
  • A compound variant’s condition on an undeclared variant never matches. An undeclared option in its list is ignored, so a condition left without a declared option never matches either.
  • In sva, classes for a slot that slots does not name are ignored.

When it is created, the recipe warns about each such name with console.warn, in one message:

A recipe's config names variants, options, or slots that it does not declare, so they add nothing:
- Compound variant 0 names the variant "tonne".

A recipe created again from a config with the same mistakes does not repeat the warning.

Each entry of compoundVariants is an object with these properties:

Property Required Description
variants Required The condition: for each variant it names, one option or a list of options. A variant it leaves out matches any option.
className Required The classes added when the condition matches.
{ variants: { tone: "danger", size: ["md", "lg"] }, className: "font-semibold" }

See Compound variants.

A recipe takes one optional argument, an object with these properties:

Property Description
Each variant, by name The option to use. Required for a variant without a default, unless it is a boolean variant.
className Optional. Classes added after every class of the recipe. It takes one string.

The recipe ignores every other property, so a component can pass it all of its props. When every variant is optional, the argument is optional too.

A recipe returns the class name as a string. It adds the classes in this order:

  1. base.
  2. The classes of each variant’s option, in the order of variants.
  3. The classes of each matching compound variant, in the order of compoundVariants.
  4. className.

The recipe builds the class name of each selection once and caches it, so a later call with the same variants is a lookup. See How it works.

className adds classes after every class of the recipe:

badge({ tone: "danger", outlined: true, className: "uppercase" })→ "inline-flex rounded-full px-2 text-xs bg-red-100 text-red-800 ring-1 ring-inset ring-current uppercase"

With the default join, these classes are added, not substituted. A class that sets the same CSS property as a class of the recipe leaves both in the class name. Design the recipe so that it needs no override (see Writing conflict-free recipes), or use a join such as twMerge (see Merging classes).

Property Type Description
variantKeys A readonly array of variant names The names of the variants, in the order of variants.
variantOptions An object of readonly arrays of strings For each variant, the names of its options.
defaultVariants An object of strings For each variant that may be left out, the option it uses then.
badge.variantKeys; // => ["tone", "outlined"]
badge.variantOptions;
// => { tone: ["neutral", "success", "danger"], outlined: ["false", "true"] }
badge.defaultVariants; // => { outlined: "false" }

These properties are frozen. See Listing the variants for the order of the options.

composes is described in Composing recipes.