Skip to content

createStyleRecipe

createStyleRecipe creates a style recipe, which returns the style of one element for a selection of variants.

import { createStyleRecipe } from "@lynstack/native-recipe";
export const badge = createStyleRecipe({
// Applied whatever the variants.
base: { alignSelf: "flex-start", borderRadius: 999, paddingHorizontal: 8 },
// For each variant, the style of each option.
variants: {
tone: {
neutral: { backgroundColor: "#f3f4f6" },
success: { backgroundColor: "#dcfce7" },
danger: { backgroundColor: "#fee2e2" },
},
outlined: {
true: { borderColor: "#d1d5db", borderWidth: 1 },
},
},
});

PlaygroundChoose the variants. The properties a choice adds or changes light up.

tone
outlined
badge({ tone: "neutral" })→ {    alignSelf: "flex-start",    borderRadius: 999,    paddingHorizontal: 8,    backgroundColor: "#f3f4f6",  }

Pass the result to the style prop of the element: <View style={badge({ tone })} />. For what variants, options, and compound variants are, see Variants.

// Simplified: the type parameters are left out.
function createStyleRecipe(config: StyleRecipeConfig): StyleRecipe;

TypeScript infers the variants, options, and style types from config, so you never write type arguments. The full types are on All exports.

Property Required Description
variants Required For each variant name, the style of each of its options. Write variants: {} when the recipe has none.
base Optional The style the element always has.
compoundVariants Optional Styles added when several variants have particular options at the same time, in order. See Compound variants.
defaultVariants Optional The option each variant uses when a call leaves it out. A variant without a default is required.
composes Optional Style recipes whose configs the recipe adds before its own. See Composing recipes.
cache Optional Whether the recipe caches its styles. Defaults to true. With false, every call returns a new object, so leave it on in components.

variants is required even when it is empty. Without it, TypeScript reports Property 'variants' is missing (TS2741):

// Error: Property 'variants' is missing.
createStyleRecipe({ base: { padding: 8 } });
createStyleRecipe({ base: { padding: 8 }, variants: {} });

In JavaScript, or in a config that bypasses the types, creating the recipe throws a TypeError that names what is wrong: no variants, a style that is not an object, or a compound variant without variants or style.

Every style is checked against the styles of React Native, as in StyleSheet.create (see Typing recipes). A style that never changes does not need a recipe: keep it in StyleSheet.create (see Building components).

A default or a compound variant can name a variant or an option that the config does not declare, such as a misspelled one. TypeScript rejects it in a config written in the call. A config declared before the call can let some through (see A config declared before the call), and JavaScript checks none. The recipe then adds no style for that name:

  • A default of an undeclared variant is ignored.
  • A default option that its variant does not declare selects no option, so a call that leaves the variant out adds no style for it. The recipe’s defaultVariants still lists that option as written.
  • A compound variant’s condition on an undeclared variant never matches. An undeclared option in its list is ignored, so a condition left without a declared option never matches either.
  • In a slot recipe, a style for a slot that slots does not name is ignored.

When it is created, the recipe warns about each such name with console.warn, in one message:

A recipe's config names variants, options, or slots that it does not declare, so they add nothing:
- Compound variant 0 names the variant "tonne".

The names of the recipes it composes count as declared. A recipe created again from a config with the same mistakes, such as a themed recipe for each theme, does not repeat the warning.

Each item of compoundVariants is an object of type StyleCompoundVariant:

Property Required Description
variants Required The condition: one option, or a list of options, for each variant it names. A variant it leaves out matches any.
style Required The style added when the condition matches.
compoundVariants: [
{ variants: { tone: "danger", size: ["sm", "md"] }, style: { borderWidth: 2 } },
],

The condition is checked after defaults apply. A condition on an undeclared variant never matches, and an undeclared option in a list is ignored; the recipe warns about both (see Names the config does not declare).

A recipe is a function. It takes a selection and returns a style:

  • Frozen. The style is a frozen object. Do not change it or spread it.
  • The same object for the same variants. The recipe builds the style of each selection once. Every later call with the same variants, including variants left to their defaults, returns that same object. So the style prop keeps its identity between renders (see How it works).
  • In a fixed order. The style merges base, then the style of each variant’s option, in the order of variants, then each matching compound variant, in the order of compoundVariants. A later style overrides the properties of an earlier one, as StyleSheet.flatten does. A property set to undefined is copied too, so it overrides an earlier value.
import { createStyleRecipe } from "@lynstack/native-recipe";
export const text = createStyleRecipe({
base: { color: "#111827", fontSize: 16 },
variants: {
size: { sm: { fontSize: 14 }, lg: { fontSize: 20 } },
muted: { true: { color: "#6b7280" } },
},
});
text({ size: "sm", muted: true })→ { color: "#6b7280", fontSize: 14 }
badge({ tone: "success" }) === badge({ tone: "success" }); // => true
Object.isFrozen(badge({ tone: "success" })); // => true

The argument is optional when every variant is optional. A call with no argument or undefined is the same as a call with {}. TypeScript rejects null; a null from untyped data counts as {} too. Props that are not variants are ignored (see Variants).

Create each recipe once, at the top level of a module, not inside a component, so that its cache lasts.

A recipe has three frozen properties that list its variants. They are typed with the names of its variants and options.

Property Description
variantKeys The names of the variants, in the order of variants.
variantOptions The options of each variant, as strings. The order: integer names first, from smallest to largest; then "false" and "true" for a boolean variant; then the other names, in the order you declare them.
defaultVariants The option, as a string, that each optional variant uses when a call leaves it out: its default, or "false" for a boolean variant.
badge.variantKeys; // => ["tone", "outlined"]
badge.variantOptions;
// => { tone: ["neutral", "success", "danger"], outlined: ["false", "true"] }
badge.defaultVariants; // => { outlined: "false" }

Use variantKeys to split a component’s props (see Building components), and variantOptions to show every look of a component.

composes lists style recipes whose configs the recipe adds before its own. The recipe accepts their variants too. See Composing recipes.

You cannot pass extra styles into a recipe call. Merge them in the style prop instead (see Building components).