Variants
A recipe turns the props of a component into class names. This page
explains how it reads those props. The rules are the same for cva and
sva.
- A recipe is the function that
cvareturns. You call it with props, and it returns a class name. - A variant is a prop that changes how the element looks, such as
toneorsize. - An option is one value of a variant, such as
"sm"or"md". The config gives the classes of each option. - A selection is the object you pass to the recipe. It chooses an option for some or all of the variants.
- A default is the option that a variant uses when the selection
leaves it out. You set it in
defaultVariants. - A slot is one element of a component made of several elements, such
as the header of a card. A slot recipe, which
svareturns, gives the class name of each slot.
The glossary lists these terms and a few more.
Required and default variants
Section titled “Required and default variants”A variant with a default may be left out, or passed as undefined. It
then uses its default. When every variant has a default, you can call the
recipe without an argument:
import { cva } from "@lynstack/class-recipe";
export const stack = cva({ variants: { gap: { sm: "gap-2", md: "gap-4" }, direction: { row: "flex-row", column: "flex-col" }, }, defaultVariants: { gap: "md", direction: "column" },});stack()→ "gap-4 flex-col"stack({ direction: "row" })→ "gap-4 flex-row"stack({ gap: undefined })→ "gap-4 flex-col"A variant without a default is required. TypeScript reports an error
when a call leaves it out, so a component cannot forget to choose it. In
the next recipe, tone has no default:
import { cva } from "@lynstack/class-recipe";
export const button = cva({ base: "inline-flex rounded-md", variants: { tone: { neutral: "bg-gray-100", danger: "bg-red-600 text-white" }, size: { sm: "h-8 px-3", md: "h-10 px-4" }, outlined: { true: "ring-1 ring-inset" }, }, compoundVariants: [ // When tone is danger and size is md. { variants: { tone: "danger", size: "md" }, className: "font-semibold" }, // When tone is neutral and outlined is true, whatever the size. { variants: { tone: "neutral", outlined: true }, className: "ring-gray-300", }, ], defaultVariants: { size: "md" },});button({ tone: "danger" })→ "inline-flex rounded-md bg-red-600 text-white h-10 px-4 font-semibold"button({ tone: "neutral", size: "sm" })→ "inline-flex rounded-md bg-gray-100 h-8 px-3"// @ts-expect-error: tone has no default, so it is required.button({ size: "sm" });To make a variant optional, give it a default. To add no classes when a
call leaves it out, declare an option without classes, such as
none: "", and make it the default.
Boolean variants
Section titled “Boolean variants”A boolean variant is a variant whose only options are true and
false. It is optional, and false by default. When you declare only one
of the two options, the recipe declares the other one, without classes.
The recipe accepts the booleans true and false, and also the strings
"true" and "false":
import { cva } from "@lynstack/class-recipe";
export const input = cva({ base: "rounded-md border", variants: { invalid: { true: "border-red-600", false: "border-gray-300" }, disabled: { true: "opacity-50" }, },});input()→ "rounded-md border border-gray-300"input({ invalid: true, disabled: true })→ "rounded-md border border-red-600 opacity-50"When a component also passes a boolean variant to an element, such as
disabled to a <button>, type that prop as boolean. VariantsOf
allows the string "false", which is truthy, so disabled="false" would
disable the button.
Option names that are numbers
Section titled “Option names that are numbers”When an option’s name is a number, the recipe accepts the number and the string:
import { cva } from "@lynstack/class-recipe";
export const heading = cva({ variants: { level: { 1: "text-3xl", 2: "text-2xl" } },});heading({ level: 1 })→ "text-3xl"heading({ level: "2" })→ "text-2xl"Write the name without quotes, as 1:. TypeScript reads a quoted name,
"1":, as a string, so the option then accepts only "1" in the
types, though the recipe accepts 1 at runtime.
Compound variants
Section titled “Compound variants”A compound variant adds classes only when several variants have
particular options at the same time. Each entry of compoundVariants has
this shape:
{ variants: { tone: "danger", size: "md" }, className: "font-semibold" }variantsis the condition. For each variant it names, it gives one option, or a list of options. A variant that it leaves out matches any option.classNameholds the classes to add. In a slot recipe, the entry hasclassNamesinstead, an object of classes keyed by slot name.
The button recipe above has two compound variants:
button({ tone: "danger" })→ "inline-flex rounded-md bg-red-600 text-white h-10 px-4 font-semibold"button({ tone: "danger", size: "sm" })→ "inline-flex rounded-md bg-red-600 text-white h-8 px-3"button({ tone: "neutral", outlined: true })→ "inline-flex rounded-md bg-gray-100 h-10 px-4 ring-1 ring-inset ring-gray-300"- The recipe applies the defaults first, then checks the conditions. The
first call does not pass
size, but the defaultsize: "md"matches the first compound variant. - A condition can match the
falseof a boolean variant, which a call that leaves the variant out selects. - The recipe adds the classes of the matching compound variants in the
order of
compoundVariants, after the classes of the variants. - A condition on a variant that the config does not declare never matches, and an undeclared option in a list is ignored. TypeScript reports both in a config written in the call, and the recipe warns about them when it is created (see Names the config does not declare).
In a slot recipe, a compound variant gives classes to the slots it names.
Here the header gets a border only when the card is both md and
elevated:
import { sva } from "@lynstack/class-recipe";
export const card = sva({ slots: ["root", "header", "body"], base: { root: "rounded-lg border", header: "font-semibold", body: "text-gray-600", }, variants: { size: { sm: { root: "p-3", header: "text-sm" }, md: { root: "p-5", header: "text-base" }, }, elevated: { true: { root: "shadow-md" }, }, }, compoundVariants: [ { variants: { size: "md", elevated: true }, classNames: { header: "border-b" }, }, ], defaultVariants: { size: "md" },});card({ elevated: true }).header→ "font-semibold text-base border-b"card({ size: "sm", elevated: true }).header→ "font-semibold text-sm"Undeclared options and other props
Section titled “Undeclared options and other props”- Undeclared options. TypeScript accepts only the options that the config declares. Untyped data, such as the values of a form, can still pass another one. An option that the variant does not declare adds no classes, and the recipe builds the class name of such a call every time, instead of caching it.
- Other props. The recipe ignores every prop that is not a variant,
apart from
className(orclassNamesfor a slot recipe). So a component can pass all of its props to its recipe.
null and undefined
Section titled “null and undefined”- A variant passed as
undefinedcounts as left out: it uses its default. - TypeScript rejects
nullas a variant’s value. Anullfrom untyped data counts as left out, likeundefined. - Calling a recipe without an argument, or with
undefined, is the same as calling it with{}. TypeScript rejectsnullas the argument; anullfrom untyped data counts as{}too.
Listing the variants
Section titled “Listing the variants”Every recipe and slot recipe has three properties that list its variants. They are frozen, and typed with the names of the variants and options:
| Property | What it holds |
|---|---|
variantKeys |
The names of the variants, in the order of variants. |
variantOptions |
For each variant, the names of its options, as strings. Integer names come first, in ascending order; then "false" and "true", for a variant that declares either one; then the other names, in the order the config declares them. |
defaultVariants |
For each variant that may be left out, the option it uses then, as a string: its default, or "false" for a boolean variant. |
For the button recipe above:
button.variantKeys; // => ["tone", "size", "outlined"]button.variantOptions;// => { tone: ["neutral", "danger"], size: ["sm", "md"], outlined: ["false", "true"] }button.defaultVariants; // => { size: "md", outlined: "false" }Use variantKeys to split a component’s props into variants and the rest
(see Building components).
Use variantOptions to render every look of a component, such as in a
story for each option, or in a test that calls the recipe with each
selection.
Next steps
Section titled “Next steps”- Composing recipes builds a recipe from others.
- Writing conflict-free recipes shows how to choose the classes of each option.
- cva and sva list every property of a config.