Tailwind Merge Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require gehrisandro/tailwind-merge-laravel
   

   Publish config (optional):

   php artisan vendor:publish --provider="TailwindMerge\Laravel\TailwindMergeServiceProvider"
   

2. First Use Case: In a Blade component, replace $attributes->class with $attributes->twMerge():

   <!-- components/button.blade.php -->
   <button {{ $attributes->twMerge('px-4 py-2 bg-blue-500 text-white') }}>
       Click Me
   </button>
   

   Override in parent view:

   <x-button class="bg-red-500 hover:bg-red-600" />
   

   Output: <button class="px-4 py-2 bg-red-500 text-white hover:bg-red-600">

Implementation Patterns

Blade Component Workflow

1. Define Base Classes:

   <!-- components/card.blade.php -->
   <div {{ $attributes->twMerge('p-6 rounded-lg shadow-md bg-white') }}>
       {{ $slot }}
   </div>
   

2. Override in Parent View:

   <x-card class="bg-gray-100 p-4 rounded-none">
       Content
   </x-card>
   

3. Multi-Element Merging (for nested elements):

   <!-- components/avatar.blade.php -->
   <div {{ $attributes->withoutTwMergeClasses()->twMerge('flex items-center') }}>
       <img {{ $attributes->twMergeFor('img', 'w-10 h-10 rounded-full') }} src="{{ $src }}" alt="{{ $alt }}">
       <span {{ $attributes->twMergeFor('name', 'ml-3') }}>{{ $name }}</span>
   </div>
   

   Usage:

   <x-avatar class="items-start" class:img="w-12" class:name="ml-4" />
   

Blade Directive Pattern

Use @twMerge for inline class merging:

<div @twMerge('text-lg', 'text-red-500')>Text</div>

Facade/Helper Pattern

For non-Blade contexts (e.g., email templates, API responses):

use TailwindMerge\Laravel\Facades\TailwindMerge;

// In a service or controller
$mergedClasses = TailwindMerge::merge('bg-blue-500 hover:bg-blue-600', 'bg-red-500');

// Or via helper
$merged = twMerge('p-4', 'p-6');

Dynamic Class Generation

Merge classes dynamically based on conditions:

<div {{ $attributes->twMerge(
    'bg-' . ($isActive ? 'green' : 'gray') . '-500',
    'hover:bg-' . ($isActive ? 'green' : 'gray') . '-600'
) }}>
    Content
</div>

Gotchas and Tips

Common Pitfalls

1. Non-Tailwind Classes:

   • Non-Tailwind classes (e.g., custom-class) are preserved but may cause unexpected behavior if they conflict with Tailwind’s internal logic.
   • Fix: Explicitly list them in config/tailwind-merge.php under classGroups:

     'classGroups' => [
         'custom' => [['custom-class']],
     ],
     

2. Arbitrary Values:

   • Arbitrary values (e.g., w-[200px]) always win. Later arbitrary values override earlier ones.
   • Tip: Use !important equivalents (e.g., !w-[200px]) for explicit overrides.

3. Dark Mode Conflicts:

   • Dark mode classes (e.g., dark:bg-gray-800) are merged like any other class, but ensure your custom dark variants are registered in classGroups.

4. Cache Invalidation:

   • The package caches merged classes. Clear cache after updating classGroups:

     php artisan cache:clear
     

Debugging Tips

1. Inspect Merged Output: Use the facade to debug:

   dd(TailwindMerge::merge('class1', 'class2')); // Inspect merged result
   

2. Validate Tailwind Config: If merging fails, ensure your tailwind.config.js aligns with the package’s assumptions (e.g., no conflicting color names like bg-primary).

3. Check for Typos: The package throws exceptions for invalid Tailwind classes. Use TailwindMerge::validate() to pre-check:

   if (!TailwindMerge::validate('invalid-class')) {
       // Handle error
   }
   

Advanced Patterns

1. Custom Class Groups: Extend classGroups for custom utilities (e.g., bg-brand-*):

   // config/tailwind-merge.php
   'classGroups' => [
       'brand' => [
           ['bg' => ['brand-50', 'brand-100', 'brand-500']],
       ],
   ],
   

2. Dynamic Prefixes: Override the prefix globally via .env:

   TAILWIND_MERGE_PREFIX=tw-
   

3. Performance: For high-traffic apps, disable caching in config/tailwind-merge.php:

   'cache' => false,
   

4. Testing: Mock the facade in tests:

   TailwindMerge::shouldReceive('merge')
       ->once()
       ->with('expected-classes')
       ->andReturn('merged-classes');
   

Edge Cases

• Empty Inputs: twMerge('') returns an empty string.
• Whitespace: Extra spaces are trimmed (e.g., twMerge(' p-4 ', 'p-6') → p-6).
• State Conflicts: Hover/focus states (e.g., hover:bg-red-500) are merged like static classes.