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", }, },});Signature
Section titled “Signature”import { cva } from "@lynstack/class-recipe";
const recipe = cva(config);recipe(props); // => stringcva 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).
The config
Section titled “The config”| 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.
Names the config does not declare
Section titled “Names the config does not declare”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
defaultVariantsstill 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 thatslotsdoes 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.
A compound variant
Section titled “A compound variant”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.
The call
Section titled “The call”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.
The result
Section titled “The result”A recipe returns the class name as a string. It adds the classes in this order:
base.- The classes of each variant’s option, in the order of
variants. - The classes of each matching compound variant, in the order of
compoundVariants. 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.
Overriding classes
Section titled “Overriding classes”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).
Listing the variants
Section titled “Listing the variants”| 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.
Composing recipes
Section titled “Composing recipes”composes is described in
Composing recipes.