Skip to content

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.

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.

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:

  1. The base of each composed recipe, then its own base.
  2. For each variant, the composed recipe’s style for the option, then its own.
  3. The compound variants of each composed recipe, then its own.

When several recipes give a default to the same variant, the last one wins.

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 },
},
],
});
  • variants is still required. A recipe that only composes others declares variants: {}.
  • 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.

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.

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].