Skip to content

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.

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

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.

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.

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.

  • A config without variants throws a TypeError that says so when you create the recipe. Pass variants: {}.
  • Listing anything other than a recipe of the package in composes is a type error. It also throws a TypeError when you create the recipe.
  • The same TypeError happens 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 with npm dedupe.