tailwind-impl-tailwind-merge

name	tailwind-impl-tailwind-merge
description	Use when composing Tailwind class strings dynamically across React, Vue, Svelte, Solid, or any framework where a parent component passes override classes to a child via a className prop, and the child combines them with its own defaults. Solves the duplicate-utility problem (twMerge('p-2 p-4') -> 'p-4') so the LAST value wins deterministically instead of the cascade emitting both and the outcome depending on stylesheet ordering. Prevents the ineffective-override trap (passing 'p-4' to a child whose default is 'p-2 text-blue-500' leaves BOTH padding classes in the markup, and whichever the bundler ships later wins), the stale-cache trap (calling extendTailwindMerge inside a render path on every render rebuilds the big data structure), the wrong-package-version trap (tailwind-merge v2.x is for Tailwind v3, v3.x is for Tailwind v4), and the prefix-mismatch trap (custom Tailwind prefix tw- requires configuring tailwind-merge with that prefix or merges silently return wrong output). Covers twMerge / twJoin / extendTailwindMerge / createTailwindMerge / getDefaultConfig / mergeConfigs / fromTheme / validators, the shadcn/ui cn helper pattern (clsx + twMerge), class-variance-authority (cva) integration with base + variants + compoundVariants + defaultVariants, the VariantProps TypeScript type, custom utility registration for design-system tokens, prefix support, cacheSize tuning, when to use twMerge vs twJoin vs plain string concatenation. Keywords: tailwind-merge, twMerge, twJoin, clsx tailwind, cn helper, shadcn cn, class-variance-authority, cva, VariantProps, classnames, extendTailwindMerge, createTailwindMerge, getDefaultConfig, mergeConfigs, fromTheme, validators, conflict resolution, last wins tailwind, override className prop, conditional class names react, cacheSize, prefix tailwind merge, custom utility merge, shadcn ui button, my padding class not applied, tailwind classes both appearing, override className not working, how to merge tailwind classes, react className prop, dynamic tailwind classes, cva button pattern, variant pattern react, install tailwind-merge, tailwind-merge v2, tailwind-merge v3, tailwind-merge for tailwind v4, tailwind-merge for tailwind v3, memoize class merge, render path performance
license	MIT
compatibility	Designed for Claude Code. Requires Tailwind CSS v3.4 or v4.0+.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

tailwind-merge : Deterministic Class Override

tailwind-merge is a runtime library that takes any number of Tailwind class strings and returns ONE string where conflicting utilities are resolved with a LAST-WINS rule.

It is the foundation of the shadcn/ui cn() helper, the cva-based component variant pattern, and any React/Vue/Svelte component that accepts a className prop and combines it with internal defaults.

Companion skills :

• tailwind-impl-config-v3 and tailwind-impl-config-v4 : the Tailwind side of the equation.
• tailwind-impl-plugins-official : how the official plugins emit class groups that tailwind-merge needs to know about.
• shadcn-ui skill package : the upstream design system that popularised the cn helper.

Quick Reference : The Problem

// Component default
function Card({ className }) {
  return <div className={`p-2 bg-white ${className}`} />;
}

// Caller passes override
<Card className="p-4" />

Output markup contains p-2 bg-white p-4. The compiled CSS contains BOTH .p-2 and .p-4. Whichever appears later in the stylesheet wins. With JIT this is non-deterministic across builds.

Quick Reference : The Fix

import { twMerge } from "tailwind-merge";

function Card({ className }) {
  return <div className={twMerge("p-2 ", )} />;
}

< className= />