Skip to content

createThemedRecipes

For a theme type, createThemedRecipes returns createStyleRecipe, createSlotStyleRecipe, and themeToken. Each creator takes a function that reads the tokens from themeToken and returns the config of the recipe. Each returns a themed recipe, which takes the theme first, then the selection.

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 light: Theme = {
colors: { primary: "#2563eb", surface: "#ffffff" },
radius: 8,
};
const dark: Theme = {
colors: { primary: "#60a5fa", surface: "#111827" },
radius: 8,
};
export { button, dark, light };

button(light, { tone: "surface" }) returns the style of the light theme, and button(dark, { tone: "surface" }) the style of the dark one. They are the styles that the recipe of each theme returns, which withTheme gives:

button.withTheme(light)({ tone: "surface" })→ { borderRadius: 8, backgroundColor: "#ffffff" }
button.withTheme(dark)({ tone: "surface" })→ { borderRadius: 8, backgroundColor: "#111827" }

Call createThemedRecipes once, in a module of your own, and import its recipe creators and themeToken wherever you create recipes (see Theming with design tokens). Every recipe they create takes the theme type that you give it.

// Simplified: the type parameters of each creator are left out.
function createThemedRecipes<Theme extends object>(): {
readonly themeToken: Theme;
createStyleRecipe(
config: (theme: Theme) => StyleRecipeConfig,
): ThemedRecipe<Theme>;
createSlotStyleRecipe(
config: (theme: Theme) => SlotStyleRecipeConfig,
): ThemedRecipe<Theme>;
};

Theme is the type of your theme objects, and the return type is ThemedRecipeCreators<Theme>.

The function returns the config of a style recipe or of a slot style recipe. It has the same properties and the same checks, variants included. TypeScript infers the variants, options, and slots from what it returns. A token is typed as the theme type declares it.

The function runs once for each theme object, at the first call with that theme, and themeToken is that theme while it runs. So a token can be computed, as in themeToken.gap * 2, or branched on. Read themeToken only inside the function. Anywhere else it throws a TypeError, as in const { colors } = themeToken at the top level of a module.

Since the function runs at the first call with each theme, that call is where a config with the wrong shape throws its TypeError, and where the recipe warns about names the config does not declare.

Every theme must give the same variants, options, and slots. Only the styles may change with the theme. So when you branch on a token, branch inside a style. Never add or remove a variant or an option for one theme. For a theme with a highContrast flag:

// Right: the branch is inside the style.
createStyleRecipe(() => ({
variants: {
outlined: { true: { borderWidth: themeToken.highContrast ? 2 : 1 } },
},
}));
// Wrong: the branch is around the variant, so one theme has no `outlined`.
// TypeScript reports an error here. With exactOptionalPropertyTypes, it
// reports one at each call that sets `outlined` instead.
const box = createStyleRecipe(() => ({
variants: themeToken.highContrast
? {}
: { outlined: { true: { borderWidth: 1 } } },
}));
box(light, { outlined: true });

Write the function in the call, as () => ({ … }), and read the tokens from themeToken. While the config has an error, as it often does while you write it, your editor still completes the names of the variants, options, and slots:

createSlotStyleRecipe(() => ({
slots: ["root"],
variants: { raised: { true: { root: { elevation: 2 } } } },
// Completes `raised` after `r`.
compoundVariants: [{ variants: { r }, styles: {} }],
}));

TypeScript reports an error in base, in a compound variant, or in a token where it is. A wrong value in the style of an option, such as flexDirection: "sideways", it reports on variants, with a longer message.

The function can also take the theme as a typed parameter, as in (theme: Theme) => ({ … }). Your editor still completes the config, but TypeScript reports any error on the whole function, with a long message. With an untyped parameter, as in (theme) =>, your editor completes nothing while the config has an error.

A config declared before the call needs the typed parameter, since ThemedStyleRecipeOf and ThemedSlotStyleRecipeOf read the theme type from it (see Exporting recipes). Whichever form you use, the recipe and its checks are the same.

A themed recipe takes the theme, then the selection. The selection is optional when every variant is optional:

button(light) === button(light, { tone: "primary" }); // => true

It returns the same frozen style for the same theme object and the same variants.

A themed recipe keeps one recipe, with its own cache, for each theme object:

  • The first call with a theme object builds the config for that theme, and creates a recipe from it. Later calls with the same object reuse that recipe and its cache.
  • Each theme has its own cache. Switching to another theme and back returns the cached styles of the first theme.
  • A new object is a new theme, even with the same tokens. It builds a new recipe with an empty cache. So create each theme once, at the top level of a module, or memoize a theme that you build at runtime (see Keep each theme stable).
  • A theme object that nothing references anymore is released, with its recipe.
const surface = button(light, { tone: "surface" });
button(dark, { tone: "surface" });
button(light, { tone: "surface" }) === surface; // => true

withTheme(theme) returns the recipe of one theme. It is a plain recipe: it takes only a selection, and it has variantKeys, variantOptions, and defaultVariants. It returns the same recipe for the same theme object.

const lightButton = button.withTheme(light);
lightButton({ tone: "surface" }) === button(light, { tone: "surface" });
// => true
lightButton.variantKeys; // => ["tone"]
lightButton.variantOptions; // => { tone: ["primary", "surface"] }
lightButton.defaultVariants; // => { tone: "primary" }

Use it to:

  • Read the lists of the variants. A themed recipe has no variantKeys of its own, since it needs a theme to build its config.
  • Pass a recipe to code that takes a plain recipe, such as a child component that does not know about themes.
  • Compose a themed recipe in another one (see below).

To compose a themed recipe, list withTheme(themeToken) in composes. It returns the recipe of the theme being built, so each theme composes the recipe of the same theme:

const iconButton = createStyleRecipe(() => ({
composes: [button.withTheme(themeToken)],
base: { width: 40, height: 40 },
variants: {},
}));

A themed recipe can also compose recipes without a theme. A themed slot recipe composes the withTheme(themeToken) of another themed slot recipe in the same way. See Composing recipes for an example with its output.

createSlotStyleRecipe works the same way for slot recipes:

const { createSlotStyleRecipe, themeToken } = createThemedRecipes<Theme>();
const card = createSlotStyleRecipe(() => ({
slots: ["root", "title"],
base: {
root: { borderRadius: themeToken.radius },
title: { fontSize: 16 },
},
variants: {
raised: {
true: { root: { backgroundColor: themeToken.colors.surface } },
},
},
}));
card(dark, { raised: true }).root; // the root style of the dark theme

VariantsOf returns the variants of a themed recipe, as of any recipe:

import type { VariantsOf } from "@lynstack/native-recipe";
type ButtonVariants = VariantsOf<typeof button>;
// => { readonly tone?: "primary" | "surface" | undefined }

ThemedRecipe is the type of a themed recipe, and ThemedRecipeCreators the type of what createThemedRecipes returns (see All exports).