Avoiding Class Conflicts With tailwind-merge

How Tailwind Class Conflicts Arise

<!-- Both p-4 and p-8 appear in the DOM -->
<div class="p-4 p-8">...</div>
<!-- Which padding is applied? Depends on Tailwind's
     stylesheet order, not the class string order. -->

<!-- Same problem with text colors -->
<div class="text-gray-900 text-blue-500">...</div>
<!-- Will the text be gray or blue? You cannot be sure. -->

What tailwind-merge Does

import { twMerge } from 'tailwind-merge';

// Conflict resolution: last value wins
twMerge('p-4 p-8')
// Output: 'p-8'

twMerge('text-gray-900 text-blue-500')
// Output: 'text-blue-500'

twMerge('font-bold font-medium text-sm text-lg')
// Output: 'font-medium text-lg'

// Non-conflicting classes are kept
twMerge('flex items-center gap-4 p-4')
// Output: 'flex items-center gap-4 p-4'

Installing and Basic Usage

npm install tailwind-merge

import { twMerge } from 'tailwind-merge';

// Single string
const cls = twMerge('bg-blue-500 bg-red-500');
// → 'bg-red-500'

// Multiple arguments (like clsx)
const cls2 = twMerge(
  'px-4 py-2 rounded',   // base
  'px-8',                // override padding-x
  'text-white'
);
// → 'py-2 rounded px-8 text-white'

twMerge Understands Utility Groups

import { twMerge } from 'tailwind-merge';

// px and py don't conflict with each other
twMerge('px-4 py-2 px-8')
// → 'py-2 px-8'  (px-4 removed, px-8 wins)

// Hover variants are separate groups
twMerge('hover:bg-blue-500 hover:bg-red-500 bg-white')
// → 'bg-white hover:bg-red-500'

// Shadow variants
twMerge('shadow-sm shadow-lg shadow-md')
// → 'shadow-md'

// Responsive prefixes are separate groups
twMerge('md:text-xl md:text-2xl text-sm')
// → 'text-sm md:text-2xl'

The cn() Helper Pattern

// lib/utils.ts
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

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

// Usage: conditional classes with conflict resolution
function Badge({ active, className }) {
  return (
    <span
      className={cn(
        'px-2 py-1 rounded-full text-sm font-medium',
        active ? 'bg-blue-100 text-blue-800' : 'bg-gray-100 text-gray-600',
        className  // caller override — twMerge resolves conflicts
      )}
    >
      Label
    </span>
  );
}

className Prop Override Pattern

// Without twMerge: caller override might not work
function Card({ className, children }) {
  return (
    <div className={'bg-white rounded-xl p-6 shadow ' + className}>
      {children}
    </div>
  );
}
<Card className='bg-gray-50' /> // bg-white and bg-gray-50 both present!

// With twMerge: caller override always wins
function Card({ className, children }) {
  return (
    <div className={cn('bg-white rounded-xl p-6 shadow', className)}>
      {children}
    </div>
  );
}
<Card className='bg-gray-50' /> // only bg-gray-50 (bg-white removed)

Arbitrary Values and twMerge

import { twMerge } from 'tailwind-merge';

// Arbitrary values conflict with standard utilities
twMerge('p-4 p-[10px]')
// → 'p-[10px]'  (last wins)

twMerge('w-full w-[300px]')
// → 'w-[300px]'

twMerge('text-sm text-[15px]')
// → 'text-[15px]'

// Mix of standard and arbitrary
twMerge('bg-blue-500 bg-[#2563eb]')
// → 'bg-[#2563eb]'

Configuring twMerge for Custom Classes

import { extendTailwindMerge } from 'tailwind-merge';

// Tell twMerge about custom text-shadow utilities
const customTwMerge = extendTailwindMerge({
  extend: {
    classGroups: {
      'text-shadow': ['text-shadow-sm', 'text-shadow-md', 'text-shadow-lg', 'text-shadow-none']
    }
  }
});

// Now conflicts are resolved correctly
customTwMerge('text-shadow-sm text-shadow-lg')
// → 'text-shadow-lg'

// Update cn() to use the custom instance
export const cn = (...inputs) => customTwMerge(clsx(inputs));

Performance Considerations

import { createTailwindMerge, getDefaultConfig } from 'tailwind-merge';

// Create a version with a larger cache for high-volume usage
const twMerge = createTailwindMerge(getDefaultConfig);

// For critical performance: memoize with React.useMemo
function VirtualListItem({ selected, disabled, className }) {
  const itemClass = useMemo(
    () => cn(
      'flex items-center px-3 py-2',
      selected && 'bg-blue-50',
      disabled && 'opacity-50',
      className
    ),
    [selected, disabled, className]
  );
  return <div className={itemClass}>{/* ... */}</div>;
}

Common Pitfalls With tailwind-merge

import { twMerge } from 'tailwind-merge';

// Non-Tailwind classes pass through untouched
twMerge('card__header bg-white bg-gray-50')
// → 'card__header bg-gray-50'  (custom class kept, Tailwind conflict resolved)

// CSS Modules classes (hash-based) also pass through
twMerge('styles__button_abc123 bg-blue-500 bg-red-500')
// → 'styles__button_abc123 bg-red-500'

// Unknown plugin classes (without extendTailwindMerge) pass through
twMerge('text-shadow-lg text-shadow-sm')  // both kept if not configured
// → 'text-shadow-lg text-shadow-sm' (no conflict detected)

Testing With tailwind-merge

// card.test.ts
import { cn } from '@/lib/utils';
import { cardVariants } from './Card';

test('caller className overrides default bg', () => {
  const result = cn(cardVariants({ variant: 'white' }), 'bg-gray-50');
  // bg-white from variant should be removed, bg-gray-50 should win
  expect(result).not.toContain('bg-white');
  expect(result).toContain('bg-gray-50');
});

test('non-conflicting classes are additive', () => {
  const result = cn('p-6 rounded-xl', 'mt-4');
  expect(result).toContain('p-6');
  expect(result).toContain('rounded-xl');
  expect(result).toContain('mt-4');
});

Quick Check

Lesson Recap