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 }, }, },});Pass the result to the style prop of the element: <View style={badge({ tone })} />. For what variants, options, and compound
variants are, see Variants.
Signature
Section titled “Signature”// 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.
The config
Section titled “The config”| 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).
Names the config does not declare
Section titled “Names the config does not declare”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
defaultVariantsstill 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
slotsdoes 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.
Compound variants
Section titled “Compound variants”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).
The result
Section titled “The result”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
styleprop 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 ofvariants, then each matching compound variant, in the order ofcompoundVariants. A later style overrides the properties of an earlier one, asStyleSheet.flattendoes. A property set toundefinedis 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" }); // => trueObject.isFrozen(badge({ tone: "success" })); // => trueThe 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.
Listing the variants
Section titled “Listing the variants”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.
Composing recipes
Section titled “Composing recipes”composes lists style recipes whose configs the recipe adds before its
own. The recipe accepts their variants too. See
Composing recipes.
Overriding styles
Section titled “Overriding styles”You cannot pass extra styles into a recipe call. Merge them in the
style prop instead (see
Building components).
See also
Section titled “See also”- createSlotStyleRecipe styles several elements.
- createThemedRecipes builds styles from theme tokens.
- All exports lists every function and type.