How native-recipe works
A recipe is a function that you create once and call on every render.
This page explains what happens in each step, and why the style prop
stays the same object between renders.
Prepared once, a lookup after that
Section titled “Prepared once, a lookup after that”When you create a recipe, it reads its config once, and gives each option of each variant a number. A selection then becomes one integer.
- The first call with a selection merges its style, freezes it, and saves it in the recipe’s cache under that integer.
- Every later call with the same variants reads the option of each variant, finds the integer, and returns the saved style.
The cache belongs to the recipe. Create each recipe once, at the top level of a module, so that its cache lasts. A recipe created inside a component is a new recipe on every render, with an empty cache.
The cache grows with the selections that you call the recipe with. It
holds at most one style for each combination of declared options. A
config with cache: false turns it off: the recipe then builds a new
style on every call, and the style prop changes on every render. Leave
the cache on.
The order of styles
Section titled “The order of styles”A style merges, from the least to the most specific:
base.- The style of each variant’s selected option, in the order of
variants. - The style of each matching compound variant, in the order of
compoundVariants.
A later style overrides the properties of an earlier one, as in
StyleSheet.flatten. A property set to undefined is copied too.
Defaults apply before compound variants are checked, so a compound
variant can match a default option. A slot recipe merges the style of
each slot in the same order.
Composed recipes
Section titled “Composed recipes”A recipe that composes others merges their configs with its own when you
create it, theirs first (see
Composing recipes). After that, it is
one recipe with one config. So a call costs the same as a call of a recipe
written without composes, with or without the cache. The recipes it
composes keep their own configs and caches.
Stable styles
Section titled “Stable styles”For React Native, the cost of a style is in its identity. When a component
renders again and its style prop is the same object as before, React
skips comparing it, and a memoized child that receives it skips
rendering.
A style built during the render is a new object on every render. This
includes { ...base, ...sizes[size] } and an array of styles. React
compares a new object property by property, and flattens an array first.
A recipe returns the same frozen object for the same variants. So the
style prop keeps its identity as long as the variants stay the same,
like a style of StyleSheet.create declared outside the component. A
slot recipe returns the same frozen object too, with the same frozen
style for each slot. Freezing stops a component from changing a style
that every other call with the same variants shares.
One recipe for each theme
Section titled “One recipe for each theme”A themed recipe takes a theme and a selection. The first call with a theme object builds the config for that theme and creates a recipe from it. The themed recipe keeps that recipe for that object. Every later call with the same object uses that recipe and its cache. So:
- Each theme has its own cache. Switching back to a theme returns its cached styles.
- A theme object must keep its identity. A new object, even with the same tokens, creates a new recipe with an empty cache (see Theme identity).
- A theme that nothing references anymore is released, with its recipe.
Next steps
Section titled “Next steps”- Building components keeps styles stable in real components.
- Benchmarks measure the cache.
- FAQ answers common questions.