Skip to content

class-recipe with TypeScript

A recipe infers the props it accepts from its config. A library that exports its recipes, or sets isolatedDeclarations, also needs Exporting and wrapping recipes.

The inferred props follow these rules:

  • An option that a variant does not declare is a type error.
  • A variant without a default is required; a variant with a default, or a boolean variant, is optional.
  • A boolean variant accepts true, false, "true", and "false", and an option whose name is a number, written without quotes, accepts the number and the string.
  • A compound variant or a default that names an undeclared variant or option is a type error, and so is a slot that slots does not name.
import { cva } from "@lynstack/class-recipe";
const button = cva({
variants: {
tone: { neutral: "bg-gray-100", danger: "bg-red-600 text-white" },
size: { sm: "h-8 px-3", md: "h-10 px-4" },
},
defaultVariants: { size: "md" },
});
button({ tone: "danger" });
// @ts-expect-error: tone has no default, so it is required.
button({ size: "sm" });

A config written inline is inferred as it is. Declare a config written before the call as const, so that the options its compound and default variants name stay literal types. The same goes for the slots of sva: without as const, the list is a string[], so the slot recipe takes any slot name, and a misspelled slot in base, in the variants, in classNames, or in the result is not a type error.

TypeScript also checks a declared config less strictly: it reports an unknown name only in an object literal written where its type is expected. So in a declared config, a misspelled name next to a correct one is not a type error in these places:

  • the variants that a compound variant names;
  • the slots of base;
  • the slots of a compound variant’s classNames.

The recipe warns about such a name when it is created, and adds no classes for it; see Names the config does not declare. Write the config in the call when nothing needs it declared, so that TypeScript reports these names as you type.

VariantsOf returns the variants a recipe or slot recipe accepts, without className or classNames:

import type { VariantsOf } from "@lynstack/class-recipe";
type ButtonVariants = VariantsOf<typeof button>;
// => { readonly tone: "neutral" | "danger";
// readonly size?: "sm" | "md" | undefined }

See Building components for using it in a component.

VariantsOf leaves out className and classNames. To type everything a recipe accepts, overrides included, use PropsOf:

import type { PropsOf } from "@lynstack/class-recipe";
type ButtonProps = PropsOf<typeof button>;
// => { readonly tone: "neutral" | "danger";
// readonly size?: "sm" | "md" | undefined;
// readonly className?: string | undefined }

For a slot recipe, PropsOf includes classNames instead, typed with SlotClasses.

PropsOf types the props of a component. To type the recipe itself, as an exported recipe under isolatedDeclarations needs, use RecipeOf (see Exporting recipes).

The package exports RecipeProps and SlotRecipeProps, but they build the props from the parts of a config, not from a recipe. RecipeProps<Variants, DefaultedName> takes two type arguments: the type of the config’s variants, and the names of the variants that have a default. So RecipeProps<typeof button> is an error:

type Props = RecipeProps<typeof button>;
// Error: Generic type 'RecipeProps' requires 2 type argument(s).

SlotRecipeProps<Slot, Variants, DefaultedName> takes the slot names first. Use them only in code that builds on configs, such as a function that creates recipes. For a recipe, use PropsOf or VariantsOf as above.

className and classNames are the names of the overrides, so they cannot be variant names: a config that declares either is a type error.

When the classes of a recipe come from outside the code, such as a CMS or a theme file, type the data with the names of its variants and options. The recipe then checks every call as above. Write the type with type, not interface. An interface has no index signature, so it does not satisfy the type of variants, and TypeScript reports “Index signature for type ‘string’ is missing in type …”:

import { sva } from "@lynstack/class-recipe";
import type { SlotClasses } from "@lynstack/class-recipe";
type CardClasses = SlotClasses<"root" | "title">;
type CardTheme = {
readonly size: Readonly<Record<"sm" | "md", CardClasses>>;
readonly tone: Readonly<Record<"neutral" | "danger", CardClasses>>;
};
const theme: CardTheme = await fetchCardTheme();
const card = sva({
slots: ["root", "title"],
variants: theme,
defaultVariants: { size: "md", tone: "neutral" },
});
card({ size: "sm" });
// @ts-expect-error: "lg" is not a size.
card({ size: "lg" });

If the data is not checked where it arrives, parse it with a schema library whose result has these types, so that a CMS that renames an option fails there instead of adding no classes.

When the names cannot be known, as in a function that passes on a config it received, type the variants as RecipeVariants or SlotRecipeVariants. A recipe then accepts any variant name, with its option named by a string, and classNames for the declared slots:

import { sva } from "@lynstack/class-recipe";
import type { SlotRecipeVariants } from "@lynstack/class-recipe";
function createCard(variants: SlotRecipeVariants) {
return sva({ slots: ["root", "title"], variants });
}
const card = createCard(theme);
card({ size: "sm", classNames: { title: "font-bold" } });
// @ts-expect-error: an option is named by a string.
card({ size: 1 });

Such a recipe checks less:

  • Every variant is optional, and an undeclared variant or option is not a type error. It adds no classes.
  • A slot recipe also accepts classes by slot as an option, such as size: { root: "p-2" }, because TypeScript cannot leave classNames out of the names that variants may take. Such a value names no option, so the variant uses its default, if it has one.
  • VariantsOf returns Readonly<Record<string, string | undefined>>.

A function of yours that takes a config and returns its recipe is typed in Exporting and wrapping recipes.

A function that takes any recipe, such as one that lists the options of each variant for a story, cannot type its parameter as a recipe of any selection. That type can be called without variants, and a recipe with a required variant cannot, so TypeScript rejects the recipe. Type the parameter instead as a function of never, which your function does not call, with the properties it reads:

import type {
Recipe,
RecipeProps,
RecipeVariants,
} from "@lynstack/class-recipe";
type AnyRecipe = ((props: never) => string) &
Pick<
Recipe<RecipeProps<RecipeVariants, never>>,
"variantKeys" | "variantOptions" | "defaultVariants"
>;
function listOptions(recipe: AnyRecipe): readonly string[] {
return recipe.variantKeys.flatMap((key) => recipe.variantOptions[key] ?? []);
}

For a slot recipe, pick the same properties from SlotRecipe<string, SlotRecipeProps<string, SlotRecipeVariants, never>>, and intersect them with (props: never) => Readonly<Record<string, string>>. A function that calls the recipe should be generic over it instead, so that it keeps the recipe’s own props.

Before TypeScript 5.9, the work of checking a chain of recipes, each of which composes the one before, grows exponentially with its length, about twofold with each recipe. A chain of about fourteen recipes compiled in the same project fails with “Type instantiation is excessively deep and possibly infinite”, and a shorter one already slows the editor down. TypeScript 5.9 and newer check the same chain in time that grows linearly.

With an older TypeScript:

  • List the recipes in one composes rather than chaining them. The cost then grows linearly: a recipe that composes ten recipes costs about as much as the ten recipes.
  • A recipe imported from a package, through its emitted declarations, counts as one recipe, however many recipes it composes.
  • Upgrade to TypeScript 5.9 or newer.

The package exports the types of every config, props object, and recipe, such as RecipeConfig and SlotRecipeProps, for code that builds on them; see Exports. For a library of recipes of other values, build on the types of @lynstack/recipe.