Tailwind Merge Recipe

Custom Tailwind Merge Recipe for Custom CSS Variables

This guide shows how to extend tailwind-merge to properly handle custom CSS variables and theme extensions in Tailwind CSS.

Problem

When using custom CSS variables in Tailwind (via @theme inline), the default tailwind-merge doesn't recognize these custom classes, causing class conflicts and improper merging.

Solution

Extend tailwind-merge with custom validators that match your CSS variable patterns.

Implementation

import { type ClassValue, clsx } from "clsx";
import { extendTailwindMerge } from "tailwind-merge";

const customTwMerge = extendTailwindMerge({
  extend: {
    theme: {
      // Custom font sizes (text-*)
      text: [
        "fine",
        "pill",
        "meta",
        "small",
        "body",
        "large",
        "subheading",
        "heading",
        "title",
        "supersub",
        "super",
      ],

      // Custom colors with pattern validators
      color: [
        // Static color names
        "success",
        "card",
        "card-foreground",

        // Dynamic patterns using validators
        (value: string) => {
          const patterns = [
            /^(solid|fill|border|ring|background)-\w+$/,
            /^background-(subtle|ui|uihover|ui-active)$/,
            /^a-(solid|fill|border|background)(-\w+)?$/,
            /^g-\w+(-dark)?$/,
          ];
          return patterns.some((pattern) => pattern.test(value));
        },
      ],

      // Custom spacing (p-*, m-*, gap-*, etc.)
      spacing: [
        "inset",
        "nav",
        "header",
        "tab",
        "gap",
        "small",
        "major",
        (value: string) => /^w\d+$/.test(value), // w4, w5, w6, etc.
      ],

      // Custom border radius
      radius: ["soft", "button", "card", "squish"],

      // Custom containers (max-w-*)
      container: ["default", "stream", "text", "hero"],
    },
  },
});

export function cn(...inputs: ClassValue[]) {
  return customTwMerge(clsx(inputs));
}

Key Patterns

1. Static arrays: For known, finite sets of values
2. Validator functions: For dynamic patterns using regex
3. Category mapping: Match CSS variable categories to Tailwind utilities

CSS Variable Structure

Your CSS should follow consistent naming patterns:

@theme inline {
  --text-body: clamp(12px, 10.8571px + 0.4286vw, 14px);
  --text-heading: clamp(17px, 14.1429px + 0.5714vw, 22px);

  --color-accent-solid: var(--accent-solid);
  --color-g-deals: var(--g-yellow);

  --spacing-w4: clamp(10.5px, 6.5714px + 0.7857vw, 16px);
  --spacing-major: clamp(64px, 41.1429px + 4.5714vw, 96px);
}

Benefits

• Proper class merging: cn("text-body", "text-heading") → "text-heading"
• No class conflicts with custom variables
• Type-safe with proper IntelliSense support
• Maintains Tailwind's utility-first approach

Usage

// Before: classes might conflict
className={clsx("bg-accent-solid", someCondition && "bg-accent-solid-hover")}

// After: proper merging
className={cn("bg-accent-solid", someCondition && "bg-accent-solid-hover")}

Converted and distributed by TomeVault — claim your Tome and manage your conversions.