Composing recipes
Several components often share classes and variants. For example, every
button-like element shares a shape, tones, and sizes. Put what they share
in one recipe, and list that recipe in the composes of the others. A
recipe that composes another accepts its variants too, and adds its own
classes after the other recipe’s classes.
Compose a recipe
Section titled “Compose a recipe”iconButton composes button. It adds a base class and a width for each
size:
import { cva } from "@lynstack/class-recipe";
import { button } from "./button.ts";
export const iconButton = cva({ composes: [button], base: "justify-center", variants: { size: { sm: "w-8", md: "w-10" }, },});iconButton({ tone: "neutral" })→ "inline-flex items-center rounded-md justify-center bg-gray-100 h-10 px-4 w-10"iconButton({ tone: "danger", size: "sm" })→ "inline-flex items-center rounded-md justify-center bg-red-600 text-white h-8 px-3 w-8"The recipe behaves as if you had written the configs in one config:
- Base classes. The base classes of the composed recipes come first, then the recipe’s own.
- Options. When several recipes give classes to the same option, such
as
size: "sm", the recipe adds the classes of the composed recipes first, then its own. - Compound variants. The compound variants of the composed recipes come before the recipe’s own.
- Defaults. When several recipes give a variant a default, the last one wins, and the recipe’s own default comes last.
- Variants. The recipe accepts the variants of every recipe it composes. A variant that has no default in any of them stays required.
composes takes a list. The recipe adds the recipes in the order of the
list. A recipe that appears twice, directly or through another recipe,
counts once.
A recipe that only composes others still needs variants. Pass
variants: {}:
const primaryButton = cva({ composes: [button], variants: {}, defaultVariants: { tone: "danger" },});Compose a slot recipe
Section titled “Compose a slot recipe”A slot recipe composes other slot recipes in the same way. It has the
slots of each composed recipe, theirs first, then the slots it adds. It
can give classes to any of them. Here, dialog composes the card slot
recipe and adds a footer slot:
import { sva } from "@lynstack/class-recipe";
import { card } from "./card.ts";
export const dialog = sva({ composes: [card], slots: ["footer"], base: { root: "max-w-lg", footer: "flex justify-end gap-2" }, variants: { size: { sm: { footer: "pt-2" }, md: { footer: "pt-4" } }, },});dialog({ size: "sm" })→ { root: "rounded-lg border max-w-lg p-3", header: "font-semibold text-sm", body: "text-gray-600", footer: "flex justify-end gap-2 pt-2", }classNames, passed to dialog, adds classes to every slot, including the
slots that come from card.
A recipe composes only recipes, and a slot recipe only slot recipes.
Composing adds classes
Section titled “Composing adds classes”A recipe that composes another adds classes after the other’s classes. It
never removes one. With the default join, both classes stay when two of
them set the same CSS property, and the stylesheet decides which one
wins. So set each CSS property of an element in one recipe only (see
Writing conflict-free recipes),
or create your recipes with a join that merges classes, such as twMerge
(see Merging classes).
A recipe created by createRecipes
can compose any recipe of the package. It joins all the classes with its
own join function.
What it costs
Section titled “What it costs”A recipe merges the configs it composes once, when you create it. After that, it costs what one recipe with the merged config costs, with or without the cache.
Before TypeScript 5.9, type checking a long chain of recipes, each of which composes the one before, slows down quickly; see Chains of composed recipes.
Errors
Section titled “Errors”- A config without
variantsthrows aTypeErrorthat says so when you create the recipe. Passvariants: {}. - Listing anything other than a recipe of the package in
composesis a type error. It also throws aTypeErrorwhen you create the recipe. - The same
TypeErrorhappens when an app installs two copies of@lynstack/recipe, the package that class-recipe is built on. Each copy knows only its own recipes. Make sure the app installs one copy, for example withnpm dedupe.
Next steps
Section titled “Next steps”- Exporting and wrapping recipes
exports recipes that other modules compose, including with
isolatedDeclarations. - Writing conflict-free recipes shows what a composing recipe should and should not set.
- Cookbook has complete recipes for common components.
- How it works explains the order of the classes and the cache.