Skip to content

sva

sva creates a slot recipe, which styles a component made of several elements, its slots, and returns an object with the class name of every slot. It is also exported as createSlotRecipe. For how variants work, read Variants first.

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" },
});

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

size
elevated
card()→ {    root: "rounded-lg border p-5",    header: "font-semibold text-base",    body: "text-gray-600",  }
import { sva } from "@lynstack/class-recipe";
const slotRecipe = sva(config);
slotRecipe(props); // => { [slot]: string }

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

The config of a slot recipe is the config of a recipe, with slots. Wherever a recipe takes a string of classes, a slot recipe takes an object of classes keyed by slot name, such as { root: "p-4", title: "font-bold" }.

Property Required Description
slots Required The names of the slots, in the order of the result.
variants Required For each variant name, the classes of each slot for each of its options. Pass variants: {} when the slot recipe has no variants. className and classNames are reserved.
base Optional The classes each slot always has.
compoundVariants Optional A list of compound variants: classes added to some slots 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 Slot recipes whose configs the slot recipe adds before its own; see Composing recipes.
cache Optional Whether the slot 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 slot recipe throws a TypeError that names the problem: a missing variants, classes given as a string instead of an object keyed by slot, or a compound variant without variants or classNames.

An option or a compound variant gives classes only to the slots it names. A slot that neither slots nor the slot recipes it composes name is a type error. Its classes are ignored, and the slot recipe warns about it when it is created (see Names the config does not declare).

A slot named after a property that every object has, such as toString or constructor, is not supported. Every object inherits that property with a function type, so the types reject an object of slot classes that leaves that slot out.

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.
classNames Required The classes added when the condition matches, keyed by slot name.
{ variants: { size: "md", elevated: true }, classNames: { header: "border-b" } }

See Compound variants.

A slot 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.
classNames Optional. Classes added after every class of some slots, keyed by slot name, such as { body: "italic" }.

The slot 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 slot recipe returns an object with the class name of every slot, in the order of slots, and "" for a slot without classes. Each slot’s classes come in the order of a recipe: base, the variants, the matching compound variants, then the slot’s classNames.

The object is frozen. Calling the slot recipe again with the same variants returns the same object, which keeps props stable for memoized components:

card({ elevated: true }) === card({ elevated: true }); // => true

classNames adds classes after every class of the slots it names:

card({ size: "sm", classNames: { body: "italic" } })→ {    root: "rounded-lg border p-3",    header: "font-semibold text-sm",    body: "text-gray-600 italic",  }

A call that passes classNames with at least one class returns a new object, and leaves the cached one unchanged. With the default join, these classes are added, not substituted: a class that sets the same CSS property as a class of the slot leaves both in its class name. Design the slot recipe so that it needs no override (see Writing conflict-free recipes), or use a join such as twMerge (see Merging classes).

A slot recipe has the same variantKeys, variantOptions, and defaultVariants as a recipe (see cva):

card.variantKeys; // => ["size", "elevated"]
card.variantOptions;
// => { size: ["sm", "md"], elevated: ["false", "true"] }
card.defaultVariants; // => { size: "md", elevated: "false" }

Use variantKeys to split a component’s props into the variants and the rest (see Building components).