Skip to content

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 cva returns. You call it with props, and it returns a class name.
  • A variant is a prop that changes how the element looks, such as tone or size.
  • 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 sva returns, gives the class name of each slot.

The glossary lists these terms and a few more.

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.

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.

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.

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" }
  • variants is 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.
  • className holds the classes to add. In a slot recipe, the entry has classNames instead, 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 default size: "md" matches the first compound variant.
  • A condition can match the false of 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. 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 (or classNames for a slot recipe). So a component can pass all of its props to its recipe.
  • A variant passed as undefined counts as left out: it uses its default.
  • TypeScript rejects null as a variant’s value. A null from untyped data counts as left out, like undefined.
  • Calling a recipe without an argument, or with undefined, is the same as calling it with {}. TypeScript rejects null as the argument; a null from untyped data counts as {} too.

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.