Skip to content

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 label of a button. A slot recipe returns one style for each slot. You choose the slot names.

The glossary has every term.

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" });

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.

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.

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" },
});

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

tone
size
outlined
button({ tone: "neutral" })→ { borderRadius: 8, backgroundColor: "#f3f4f6", height: 40 }

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.

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.

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.

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.
  • null and undefined. Calling a recipe with no argument, or with undefined, is the same as calling it with {}, and a variant set to undefined uses its default. TypeScript rejects null; a null from untyped data counts as undefined.