Writing conflict-free recipes
By default, a recipe joins its classes with cx, which keeps every class.
Two classes conflict when they set the same CSS property on one
element, such as px-4 and px-2. Then the class defined later in the
stylesheet wins, whatever their order in the class name. The result can
look right on one page and wrong on another.
You can avoid conflicts by design: set each CSS property of an element in
one place only. Then there is nothing to resolve, and you need no
tailwind-merge. The rules below show how. Each one shows a recipe that
conflicts, then the same recipe without the conflict.
Set each property in base or in one variant
Section titled “Set each property in base or in one variant”Never set a property in base and again in a variant. Give every option
of the variant its own class instead, rather than a default in base
that an option overrides.
Before, base and invalid both set the border color, so an invalid
input has two border colors:
import { cva } from "@lynstack/class-recipe";
// Conflicting: base and the variant both set the border color.export const conflicting = cva({ base: "rounded-md border border-gray-300", variants: { invalid: { true: "border-red-600" } },});conflicting({ invalid: true })→ "rounded-md border border-gray-300 border-red-600"After, only the variant sets it, with one class for each option:
import { cva } from "@lynstack/class-recipe";
// Conflict-free: only the variant sets it.export const input = cva({ base: "rounded-md border", variants: { invalid: { true: "border-red-600", false: "border-gray-300" }, },});input()→ "rounded-md border border-gray-300"input({ invalid: true })→ "rounded-md border border-red-600"Put a class that every option shares in base, and a class that differs
between options in every option of the variant. Declare an option even
when it adds no classes, with "", so that every choice has a name that
callers can pass.
Turn props that set the same property into one variant
Section titled “Turn props that set the same property into one variant”When two props set the same property, such as loading and disabled,
which both set the cursor and the opacity, a call can choose both:
import { cva } from "@lynstack/class-recipe";
// Conflicting: loading and disabled both set the cursor and the opacity.export const button = cva({ base: "inline-flex items-center rounded-md px-4 py-2", variants: { loading: { true: "cursor-wait opacity-75" }, disabled: { true: "cursor-not-allowed opacity-50" }, },});button({ loading: true, disabled: true })→ "inline-flex items-center rounded-md px-4 py-2 cursor-wait opacity-75 cursor-not-allowed opacity-50"Derive one variant from the props instead, in the component. The recipe then sees a single choice:
import { cva } from "@lynstack/class-recipe";
// Conflict-free: one variant, which the component derives from its props.export const button = cva({ base: "inline-flex items-center rounded-md px-4 py-2", variants: { state: { idle: "cursor-pointer", loading: "cursor-wait opacity-75", disabled: "cursor-not-allowed opacity-50", }, }, defaultVariants: { state: "idle" },});button({ state: "disabled" })→ "inline-flex items-center rounded-md px-4 py-2 cursor-not-allowed opacity-50"function buttonState(loading: boolean, disabled: boolean) { if (disabled) { return "disabled"; } return loading ? "loading" : "idle";}
button({ state: buttonState(loading, disabled) });Set a property that depends on several variants only in compound variants
Section titled “Set a property that depends on several variants only in compound variants”The padding of a button can depend on two variants: its size, and whether
it holds only an icon. When size sets the padding and iconOnly sets it
again, an icon button gets two paddings, and one width for every size:
import { cva } from "@lynstack/class-recipe";
// Conflicting: size sets the padding, and iconOnly sets it again.export const button = cva({ base: "inline-flex items-center justify-center rounded-md", variants: { size: { sm: "h-8 px-3 text-sm", md: "h-10 px-4 text-base" }, iconOnly: { true: "w-10 px-0" }, }, defaultVariants: { size: "md" },});button({ iconOnly: true })→ "inline-flex items-center justify-center rounded-md h-10 px-4 text-base w-10 px-0"No single variant should set such a property. Set it only in compound variants, with one compound variant for each combination:
import { cva } from "@lynstack/class-recipe";
// Conflict-free: only the compound variants set the padding and the width.export const button = cva({ base: "inline-flex items-center justify-center rounded-md", variants: { size: { sm: "h-8 text-sm", md: "h-10 text-base" }, iconOnly: { true: "", false: "" }, }, compoundVariants: [ { variants: { size: "sm", iconOnly: false }, className: "px-3" }, { variants: { size: "sm", iconOnly: true }, className: "w-8" }, { variants: { size: "md", iconOnly: false }, className: "px-4" }, { variants: { size: "md", iconOnly: true }, className: "w-10" }, ], defaultVariants: { size: "md" },});button()→ "inline-flex items-center justify-center rounded-md h-10 text-base px-4"button({ size: "sm", iconOnly: true })→ "inline-flex items-center justify-center rounded-md h-8 text-sm w-8"The options of iconOnly add no classes of their own: the compound
variants hold all of its classes.
Compose a shared recipe, and set only what it leaves alone
Section titled “Compose a shared recipe, and set only what it leaves alone”When several components share classes and variants, such as the border
and the sizes of every form control, put them in one recipe and list it in
the composes of the others (see
Composing recipes). A recipe that
composes another adds its classes after the other’s; it never replaces
them. So it must not set a property that the other recipe sets.
Before, control sets the height in size, and input sets it again:
import { cva } from "@lynstack/class-recipe";
const control = cva({ base: "rounded-md border", variants: { size: { sm: "h-8 text-sm", md: "h-10 text-base" } }, defaultVariants: { size: "md" },});
// Conflicting: control sets the height, and input sets it again.export const input = cva({ composes: [control], base: "h-9 px-3", variants: {},});input()→ "rounded-md border h-9 px-3 h-10 text-base"After, input sets only properties that control leaves alone:
import { cva } from "@lynstack/class-recipe";
const control = cva({ base: "rounded-md border", variants: { size: { sm: "h-8 text-sm", md: "h-10 text-base" } }, defaultVariants: { size: "md" },});
// Conflict-free: input sets only properties that control leaves alone.export const input = cva({ composes: [control], base: "px-3", variants: { invalid: { true: "border-red-600", false: "border-gray-300" }, },});input({ invalid: true })→ "rounded-md border px-3 h-10 text-base border-red-600"To change a property that the shared recipe sets, add an option to the shared recipe, or move the property out of it into each recipe that composes it.
Add an option rather than an override
Section titled “Add an option rather than an override”className, classNames, and compound variants add classes after the
variants; they never remove one. Passing className to change a property
that the recipe sets leaves both classes. Add an option to the variant that
owns the property instead, such as compact below. Compare the first
call, which overrides the padding, with the second, which chooses the
option:
import { cva } from "@lynstack/class-recipe";
// Conflict-free: the recipe declares the compact padding as an option.export const button = cva({ base: "inline-flex items-center rounded-md", variants: { size: { sm: "h-8 px-3", md: "h-10 px-4", compact: "h-10 px-2" }, }, defaultVariants: { size: "md" },});button({ size: "md", className: "px-2" })→ "inline-flex items-center rounded-md h-10 px-4 px-2"button({ size: "compact" })→ "inline-flex items-center rounded-md h-10 px-2"Use className and classNames only for properties that the recipe does
not set, such as margins, widths, or positions.
Pick classes with a recipe, not a lookup
Section titled “Pick classes with a recipe, not a lookup”Classes that depend on a prop belong in a recipe, not in a hand-written
object or a ternary such as tone === "danger" ? "bg-red-50" : "bg-blue-50".
A recipe keeps every option in one place, checks the options with
TypeScript, and caches the result. cx is fine for a class that sets a
property the recipe leaves alone, such as cx(classes.label, loading && "invisible").
Check a recipe
Section titled “Check a recipe”For each element, list the CSS properties that its classes set. Then ask:
- Does a property appear in more than one of
base, a variant, or compound variants that can apply together? - Does a recipe that composes another set a property that the other already sets?
- Does a call pass
classNameorclassNamesto change a property that the recipe sets?
When the answer to each is no, the recipe is conflict-free.
These rules ship with the package as an agent skill, which teaches coding agents to follow them.
Next steps
Section titled “Next steps”- Merging classes resolves
conflicts with
twMergeinstead, when you cannot avoid them. - Cookbook has conflict-free recipes for common components.
- Agent skill teaches coding agents these rules.