tailwind

Tailwind

units

Always use Tailwind units first. For custom values, always use rem, never px.

// BAD - tailwind units available but custom rem used
return <div className="p-[1.0625rem]" />;

// GOOD - uses tailwind units
return <div className="p-4.25" />;

tailwind-merge

Use tailwind-merge to concatenate class names in React components instead of template literals or array joins.

• twJoin: for conditional class combinations (no override needed)
• twMerge: allow class override (merges conflicting utilities; perfect for setting default and optional classes)

Examples

import {twMerge, twJoin} from 'tailwind-merge';

// BAD, template literals with potential conflicts
return <span className={`bg-gray-500 ${isBlue ? 'bg-blue-500' : ''}`} />;

// GOOD - twJoin for conditional classes, but no override needed
return <span className={twJoin('bg-gray-800', isBlue && 'text-blue-500')} />;

// GOOD, twMerge for override, twJoin for conditional classes
return <span className={twMerge('text-white', isBlue && 'text-blue-500')} />;

The key distinction: use twMerge when a component accepts a className prop that should be able to override defaults, twJoin would leave both conflicting classes on the element, but twMerge resolves the conflict:

// twMerge enables callers to override component defaults
function Button({className}: {className?: string}) {
  return (
    <button
      className={twMerge('bg-blue-500 px-4 py-2 text-white', className)}
    />
  );
}

// bg-red-500 wins, twMerge removes the conflicting bg-blue-500
<Button className="bg-red-500" />;

Conditional classes

Pass falsy values directly to twJoin / twMerge, they're skipped.

// correct
twJoin('base', isActive && 'bg-blue-500', error && 'border-red-500');

// ternaries that produce two positive values are fine
twJoin('base', condition ? 'a' : 'b');

Don't wrap class lists in template literals to concatenate, pass each class as a separate argument. Template literals inside twJoin / twMerge are acceptable only when interpolating a pre-built string from a lookup table (e.g., ICON_POSITION[iconPosition] from a Record<string, string>).