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" },});Signature
Section titled “Signature”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
Section titled “The config”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.
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. |
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.
The call
Section titled “The call”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.
The result
Section titled “The result”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 }); // => trueOverriding classes
Section titled “Overriding classes”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).
Listing the variants
Section titled “Listing the variants”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).