Skip to content

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.

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.

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").

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 className or classNames to 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.

  • Merging classes resolves conflicts with twMerge instead, when you cannot avoid them.
  • Cookbook has conflict-free recipes for common components.
  • Agent skill teaches coding agents these rules.