Composing recipes in native-recipe
Several components often share styles and variants. For example, a button
and an icon button share the same tones and sizes. Instead of copying the
config, put the shared part in one recipe, and list it in composes.
Compose a recipe
Section titled “Compose a recipe”Here is a shared button recipe:
import { createStyleRecipe } from "@lynstack/native-recipe";
export const button = createStyleRecipe({ base: { borderRadius: 8 }, variants: { tone: { neutral: { backgroundColor: "#f3f4f6" }, danger: { backgroundColor: "#dc2626" }, }, size: { sm: { height: 32 }, md: { height: 40 } }, outlined: { true: { borderWidth: 1 } }, }, compoundVariants: [ // When tone is danger and size is md. { variants: { tone: "danger", size: "md" }, style: { paddingHorizontal: 20 }, }, // When tone is neutral and outlined is true, whatever the size. { variants: { tone: "neutral", outlined: true }, style: { borderColor: "#d1d5db" }, }, ], defaultVariants: { size: "md" },});The recipe below composes button. It gets every variant of button,
and adds its own styles:
import { createStyleRecipe } from "@lynstack/native-recipe";
import { button } from "./button.ts";
export const iconButton = createStyleRecipe({ composes: [button], base: { alignItems: "center", justifyContent: "center" }, variants: { size: { sm: { width: 32 }, md: { width: 40 } }, },});iconButton({ tone: "neutral", size: "sm" })→ { borderRadius: 8, alignItems: "center", justifyContent: "center", backgroundColor: "#f3f4f6", height: 32, width: 32, }iconButton({ tone: "danger" })→ { borderRadius: 8, alignItems: "center", justifyContent: "center", backgroundColor: "#dc2626", height: 40, width: 40, paddingHorizontal: 20, }iconButton accepts tone, size, and outlined, the variants of
button. TypeScript knows them too, so VariantsOf<typeof iconButton>
includes them.
Which style wins
Section titled “Which style wins”Composing works as if you wrote both configs in one. The composed recipe’s styles come first, so the recipe that composes it wins when both set the same property:
- The
baseof each composed recipe, then its ownbase. - For each variant, the composed recipe’s style for the option, then its own.
- The compound variants of each composed recipe, then its own.
When several recipes give a default to the same variant, the last one wins.
Compound variants come last
Section titled “Compound variants come last”A compound variant always applies after every option. So a compound
variant of button wins over the options of iconButton.
In the example, button adds paddingHorizontal: 20 when tone is
danger and size is md. An option of iconButton cannot override
it. To override it, give iconButton its own compound variant with the
same condition:
const iconButton = createStyleRecipe({ composes: [button], variants: {}, compoundVariants: [ { variants: { tone: "danger", size: "md" }, style: { paddingHorizontal: 0 }, }, ],});variantsis still required. A recipe that only composes others declaresvariants: {}.- A recipe that appears several times in
composes, directly or through another recipe, counts once. - Compose recipes of the same type: style recipes in a style recipe, and slot recipes in a slot recipe.
- The composed recipes keep their own configs and caches. Composing does not change them.
- 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.
Compose slot recipes
Section titled “Compose slot recipes”A slot recipe composes other slot recipes in the same way. It has the
slots of each, theirs first, then its own, and it can style any of them.
Here is a card slot recipe:
import { createSlotStyleRecipe } from "@lynstack/native-recipe";
export const card = createSlotStyleRecipe({ slots: ["root", "title", "body"], base: { root: { borderRadius: 12, padding: 16 }, title: { fontSize: 18, fontWeight: "600" }, body: { fontSize: 14 }, }, variants: { tone: { plain: { root: { backgroundColor: "#ffffff" }, title: { color: "#111827" }, body: { color: "#4b5563" }, }, inverted: { root: { backgroundColor: "#111827" }, title: { color: "#ffffff" }, body: { color: "#d1d5db" }, }, }, compact: { true: { root: { padding: 8 }, title: { fontSize: 16 } }, }, }, defaultVariants: { tone: "plain" },});dialog composes it:
import { createSlotStyleRecipe } from "@lynstack/native-recipe";
import { card } from "./card.ts";
export const dialog = createSlotStyleRecipe({ composes: [card], slots: ["footer"], base: { root: { maxWidth: 480 }, footer: { flexDirection: "row", justifyContent: "flex-end", gap: 8 }, }, variants: { compact: { true: { footer: { paddingTop: 8 } } }, },});dialog({ tone: "inverted", compact: true })→ { root: { borderRadius: 12, padding: 8, maxWidth: 480, backgroundColor: "#111827", }, title: { fontSize: 16, fontWeight: "600", color: "#ffffff" }, body: { fontSize: 14, color: "#d1d5db" }, footer: { flexDirection: "row", justifyContent: "flex-end", gap: 8, paddingTop: 8, }, }dialog adds a footer slot to the slots of card, and changes the
root of card.
Compose themed recipes
Section titled “Compose themed recipes”A themed recipe composes
another themed recipe through withTheme, which returns the plain recipe
of one theme. In a config function, withTheme(themeToken) returns the
recipe of the theme being built, so the light icon button composes the
light button, and the dark icon button the dark button:
import { createThemedRecipes } from "@lynstack/native-recipe";
interface Theme { readonly colors: { readonly primary: string; readonly surface: string }; readonly radius: number;}
const { createStyleRecipe, themeToken } = createThemedRecipes<Theme>();
const button = createStyleRecipe(() => ({ base: { borderRadius: themeToken.radius }, variants: { tone: { primary: { backgroundColor: themeToken.colors.primary }, surface: { backgroundColor: themeToken.colors.surface }, }, }, defaultVariants: { tone: "primary" },}));
const iconButton = createStyleRecipe(() => ({ // The button of the same theme as this icon button. composes: [button.withTheme(themeToken)], base: { width: 40, height: 40 }, variants: {},}));
const light: Theme = { colors: { primary: "#2563eb", surface: "#ffffff" }, radius: 8,};
const dark: Theme = { colors: { primary: "#60a5fa", surface: "#111827" }, radius: 8,};
export { button, dark, iconButton, light };iconButton.withTheme(dark)({ tone: "surface" })→ { borderRadius: 8, width: 40, height: 40, backgroundColor: "#111827" }The call above is the same as iconButton(dark, { tone: "surface" }).
A themed recipe can also compose a recipe without a theme, such as
composes: [shadow].
Next steps
Section titled “Next steps”- Exporting and wrapping recipes
exports recipes that other modules compose, including with
isolatedDeclarations. - createStyleRecipe lists every property of the config.
- Theming with design tokens builds a design system with themed recipes.
- Cookbook has ready-made recipes to copy.