saltcat-unocss-merge

Utility for intelligently merging UnoCSS class names, similar to tailwind-merge but designed for UnoCSS.

Overview

When building UIs with utility-first CSS frameworks like UnoCSS, you often need to merge class names from different sources. This package intelligently handles conflicts where classes target the same CSS property, ensuring that later classes override earlier ones.

Installation

npm install saltcat-unocss-merge

Usage

import unocss from 'saltcat-unocss-merge';

// Basic usage
unocss('m-4 p-2', 'm-8');
// => 'm-8 p-2' (m-8 overrides m-4)

// With colors
unocss('bg-red-500 text-white', 'bg-blue-600');
// => 'bg-blue-600 text-white'

// With typography
unocss('text-lg font-bold', 'text-xl');
// => 'text-xl font-bold'

// Multiple inputs
unocss('m-4', 'p-2', 'font-bold', 'm-8');
// => 'm-8 p-2 font-bold'

// With arrays
unocss(['m-4', 'p-2'], ['font-bold']);
// => 'm-4 p-2 font-bold'

// Handles null/undefined/false
unocss('m-4', null, undefined, false, 'p-2');
// => 'm-4 p-2'

Features

• Smart Conflict Resolution: Automatically detects and resolves conflicts between classes that target the same CSS property
• Preserves Order: Non-conflicting classes maintain their original order
• Flexible Input: Accepts strings, arrays, or mixed inputs
• Type-Safe: Works with TypeScript (types coming soon)
• Comprehensive Coverage: Handles spacing, sizing, colors, typography, layout, flexbox, borders, effects, and more

Supported Class Categories

The merger intelligently handles conflicts for:

• Spacing: margin, padding, gap, space
• Sizing: width, height, min/max variants
• Typography: font size, weight, family, alignment, color, decorations
• Layout: display, position, overflow, z-index
• Flexbox & Grid: direction, wrap, justify, align, order, grid columns/rows
• Backgrounds: colors, gradients, size, position, repeat
• Borders: width, color, style, radius
• Effects: opacity, shadows, transforms, filters
• Transitions & Animations
• Interactivity: cursor, pointer events, user select

How It Works

1. Parsing: Each class is analyzed and categorized by its CSS property
2. Conflict Detection: Classes in the same category are identified
3. Resolution: Later classes override earlier ones in the same category
4. Merging: Non-conflicting classes are preserved and returned in order

Examples

Component Variants

function Button({ size = 'md', variant = 'primary', className }) {
  const baseClasses = 'rounded font-semibold transition';
  const sizeClasses = {
    sm: 'px-3 py-1.5 text-sm',
    md: 'px-4 py-2 text-base',
    lg: 'px-6 py-3 text-lg',
  };
  const variantClasses = {
    primary: 'bg-blue-600 text-white hover:bg-blue-700',
    secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300',
  };

  return unocss(
    baseClasses,
    sizeClasses[size],
    variantClasses[variant],
    className // User overrides
  );
}

// Usage
Button({ size: 'lg', className: 'bg-red-600' });
// => 'rounded font-semibold transition px-6 py-3 text-lg bg-red-600 text-white hover:bg-blue-700'
// Note: bg-red-600 overrides bg-blue-600

Conditional Classes

const cardClasses = unocss(
  'p-4 rounded shadow',
  isActive && 'border-2 border-blue-500',
  isLarge ? 'p-8' : 'p-4'
);
// When isLarge=true: 'p-8 rounded shadow ...'

Development

# Install dependencies
npm install

# Run tests
npm test

# Watch tests
npm run test:watch

# Coverage
npm run test:coverage

# Build
npm run build

License

MIT - Durable Programming, LLC

Credits

Inspired by tailwind-merge but designed specifically for UnoCSS naming conventions.