Variants in native-recipe
This page explains how a recipe turns props into styles. It uses a few words:
- A recipe is a function made from your style config. You call it with props, and it returns a style.
- A variant is a prop that changes the style, such as
size. - An option is one value of a variant, such as
"sm". - A selection is the variants you pass in one call, such as
{ size: "sm" }. - A slot is one element of a component, such as the
labelof a button. A slot recipe returns one style for each slot. You choose the slot names.
The glossary has every term.
Required and default variants
Section titled “Required and default variants”A variant with a default in defaultVariants is optional. When a call
leaves it out, or passes undefined, the recipe uses the default.
A variant without a default is required. TypeScript reports an error when a call leaves it out, so a component cannot forget to choose it. When every variant is optional, you can call the recipe with no argument.
import { createStyleRecipe } from "@lynstack/native-recipe";
export const avatar = createStyleRecipe({ base: { backgroundColor: "#e5e7eb" }, variants: { // No default: every call must choose a size. size: { sm: { width: 24, height: 24 }, lg: { width: 48, height: 48 }, }, // A default: a call may leave the shape out. shape: { circle: { borderRadius: 999 }, square: { borderRadius: 4 }, }, }, defaultVariants: { shape: "circle" },});avatar({ size: "sm" })→ { backgroundColor: "#e5e7eb", width: 24, height: 24, borderRadius: 999 }avatar({ size: "lg", shape: "square" })→ { backgroundColor: "#e5e7eb", width: 48, height: 48, borderRadius: 4 }avatar({ size: "sm", shape: undefined })→ { backgroundColor: "#e5e7eb", width: 24, height: 24, borderRadius: 999 }// Error: size is required.avatar({ shape: "square" });Boolean variants
Section titled “Boolean variants”A variant with an option named true or false is a boolean variant. It
takes the booleans true and false, as well as the strings.
If you declare only true, the recipe adds an empty false option. If
the variant has only these two options, it is optional, and its default
is false.
import { createStyleRecipe } from "@lynstack/native-recipe";
export const input = createStyleRecipe({ base: { borderRadius: 6, borderWidth: 1 }, variants: { invalid: { true: { borderColor: "#dc2626" }, false: { borderColor: "#d1d5db" }, }, disabled: { true: { opacity: 0.5 } }, },});input()→ { borderRadius: 6, borderWidth: 1, borderColor: "#d1d5db" }input({ invalid: true, disabled: true })→ { borderRadius: 6, borderWidth: 1, borderColor: "#dc2626", opacity: 0.5, }Here invalid declares both options, so false has a style of its own.
disabled declares only true.
When a component also passes a boolean variant to an element, such as
disabled to a Pressable, type that prop as boolean. VariantsOf
allows the string "false", which is truthy, so disabled="false" would
disable the pressable.
Option names that are numbers
Section titled “Option names that are numbers”An option whose name is a number accepts that number as well as the string:
import { createStyleRecipe } from "@lynstack/native-recipe";
export const heading = createStyleRecipe({ variants: { level: { 1: { fontSize: 32 }, 2: { fontSize: 24 } } },});heading({ level: 1 })→ { fontSize: 32 }heading({ level: "2" })→ { fontSize: 24 }Write the name without quotes, as 1:. TypeScript reads a quoted name,
"1":, as a string, so the option then accepts only "1" in the
types, though the recipe accepts 1 at runtime.
Compound variants
Section titled “Compound variants”A compound variant adds a style when several variants have particular options at the same time. Each one is an object with two properties:
{ // The condition: one option, or a list of options, for each variant // it names. A variant it leaves out matches any option. variants: { tone: "danger", size: ["sm", "md"] }, // The style to add when the condition matches. style: { paddingHorizontal: 20 },}A slot recipe uses styles instead of style, with a style for each slot
it changes: styles: { label: { opacity: 0.5 } }.
import { createStyleRecipe } from "@lynstack/native-recipe";
export const button = createStyleRecipe({ base: { borderRadius: 8 }, variants: { tone: { neutral: { backgroundColor: "#f3f4f6" }, danger: { backgroundColor: "#dc2626" }, }, size: { sm: { height: 32 }, md: { height: 40 } }, outlined: { true: { borderWidth: 1 } }, }, compoundVariants: [ // When tone is danger and size is md. { variants: { tone: "danger", size: "md" }, style: { paddingHorizontal: 20 }, }, // When tone is neutral and outlined is true, whatever the size. { variants: { tone: "neutral", outlined: true }, style: { borderColor: "#d1d5db" }, }, ], defaultVariants: { size: "md" },});The recipe checks the condition after it applies the defaults. So
{ tone: "danger" } matches the first compound variant: size is md
by default. When several compound variants match, they apply in the order
you declare them, after the styles of the variants.
In a slot recipe
Section titled “In a slot recipe”A slot recipe works the same way. The only difference is the shape of each style: an option gives a style for each slot it changes, and a slot it leaves out gets nothing from that option.
const field = createSlotStyleRecipe({ slots: ["label", "input"], variants: { invalid: { true: { label: { color: "#b91c1c" }, input: { borderColor: "#dc2626" } }, }, },});The result always has every slot. A slot with no style is an empty object. See createSlotStyleRecipe.
Listing the variants
Section titled “Listing the variants”Every recipe has three properties that list its variants. Use them to split a component’s props, or to show every look of a component, such as in a story for each option:
variantKeys: the names of the variants.variantOptions: the options of each variant, as strings.defaultVariants: the option each optional variant uses.
button.variantKeys; // => ["tone", "size", "outlined"]button.variantOptions;// => { tone: ["neutral", "danger"], size: ["sm", "md"], outlined: ["false", "true"] }button.defaultVariants; // => { size: "md", outlined: "false" }The reference gives the exact order of the options.
Details
Section titled “Details”You can stop reading here. These rules matter only for untyped data and edge cases.
- Undeclared options. The types accept only the options that the config declares. A value from untyped data, such as JSON, can still get through. An option that the variant does not declare adds no style. The recipe does not cache its style, so it builds a new object on every call.
- Other props. The recipe ignores props that are not variants. So a component can pass all of its props to the recipe.
nullandundefined. Calling a recipe with no argument, or withundefined, is the same as calling it with{}, and a variant set toundefineduses its default. TypeScript rejectsnull; anullfrom untyped data counts asundefined.
Next steps
Section titled “Next steps”- Composing recipes reuses the variants and styles of one recipe in another.
- How it works explains the cache and the order of styles.
- Cookbook has ready-made recipes to copy.