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.
Signature
Section titled “Signature”// 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 config function
Section titled “The config function”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 });Writing the config function
Section titled “Writing the config function”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.
Calling a themed recipe
Section titled “Calling a themed recipe”A themed recipe takes the theme, then the selection. The selection is optional when every variant is optional:
button(light) === button(light, { tone: "primary" }); // => trueIt returns the same frozen style for the same theme object and the same variants.
Theme identity
Section titled “Theme identity”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; // => truewithTheme
Section titled “withTheme”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" });// => truelightButton.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
variantKeysof 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).
Composing themed recipes
Section titled “Composing themed recipes”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.
Slot recipes
Section titled “Slot recipes”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 themeVariantsOf 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).