Tailwind Merge

Resolve Tailwind class conflicts intelligently with tailwind-merge for safe className composition and overrides

When to Use

• Components that accept a

  className

  prop for consumer overrides
• Merging base styles with conditional styles without conflicts
• Building reusable components where

  px-4

  should be overridable by

  px-8

• Any situation where two Tailwind classes conflict (e.g.,

  text-red-500

  and

  text-blue-500

  )

Instructions

1. Install

   tailwind-merge

   and

   clsx

   :

   npm install tailwind-merge clsx

   .
2. Create a

   cn()

   utility that combines both. Use it everywhere instead of raw

   className

   concatenation.
3. The last conflicting class wins.

   cn('px-4', 'px-8')

   outputs

   px-8

   , not

   px-4 px-8

   .

4. tailwind-merge

   understands Tailwind's class groups — it knows

   p-4

   and

   px-4

   conflict partially,

   text-red-500

   and

   text-blue-500

   conflict fully.
5. Use

   cn()

   in all component className props to allow safe overrides.

// lib/utils.ts — the cn() helper
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

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

// Component that supports className overrides
function Card({ className, children }: { className?: string; children: React.ReactNode }) {
  return (
    <div
      className={cn(
        'rounded-lg border border-gray-200 bg-white p-6 shadow-sm', // defaults
        className // consumer can override any of these
      )}
    >
      {children}
    </div>
  );
}

// Usage — override padding and remove shadow
<Card className="p-4 shadow-none">Compact card</Card>;
// Output: "rounded-lg border border-gray-200 bg-white p-4"
// p-6 was replaced by p-4, shadow-sm was replaced by shadow-none

// Conditional classes with cn()
function Alert({ variant, className }: { variant: 'info' | 'error'; className?: string }) {
  return (
    <div
      className={cn(
        'rounded-md p-4 text-sm',
        variant === 'info' && 'bg-blue-50 text-blue-700 border-blue-200',
        variant === 'error' && 'bg-red-50 text-red-700 border-red-200',
        className
      )}
    ></div>
  );
}

// Override just the background
<Alert variant="info" className="bg-blue-100" />;
// bg-blue-50 is replaced by bg-blue-100, text and border unchanged

Details

Why not just string concatenation? CSS specificity is not determined by class order —

class="px-4 px-8"

applies whichever rule comes last in the stylesheet, which depends on Tailwind's generated order, not your class string order.

tailwind-merge

resolves this by removing the conflicting class.

What tailwind-merge knows:

• p-4

  and

  px-8

  conflict on the x-axis padding (px-8 wins for x, p-4 applies to y)

• text-red-500

  and

  text-blue-500

  conflict (same property: color)

• text-lg

  and

  text-red-500

  do NOT conflict (font-size vs color)

• rounded-lg

  and

  rounded-none

  conflict (border-radius)

• hover:bg-red-500

  and

  hover:bg-blue-500

  conflict (same pseudo + property)

clsx role in cn():

clsx

handles conditional logic (booleans, arrays, objects).

twMerge

handles conflict resolution. Together:

cn(
  'base-class', // always applied
  isActive && 'bg-blue-500', // conditional (clsx)
  { 'font-bold': isBold }, // object syntax (clsx)
  className // override (twMerge resolves conflicts)
);

Custom tailwind-merge config: If you extended Tailwind with custom utilities, tell tailwind-merge about them:

import { extendTailwindMerge } from 'tailwind-merge';

const customTwMerge = extendTailwindMerge({
  extend: {
    classGroups: {
      'custom-size': ['size-sm', 'size-md', 'size-lg'],
    },
  },
});

Performance:

tailwind-merge

caches results. The first call for a given input is ~0.1ms; subsequent calls are ~0.001ms. No measurable impact on render performance.

Source

https://github.com/dcastil/tailwind-merge

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.