TailwindMerge for Laravel

To allow overriding classes in Blade components, use the $attributes->twMerge() method inside your component template. This resolves conflicts by ensuring classes passed from the parent view take precedence over the component's default classes.

Note: Do not use $attributes->merge(['class' => '...']) as it is not supported due to Laravel limitations.

Example: Basic Component

Component (circle.blade.php):

<div {{ $attributes->twMerge('w-10 h-10 rounded-full bg-red-500') }}></div>

Usage (your-view.blade.php):

<x-circle class="bg-blue-500" />

Output:

<div class="w-10 h-10 rounded-full bg-blue-500"></div>

// circle.blade.php
<div {{ $attributes->twMerge('w-10 h-10 rounded-full bg-red-500') }}></div>

Install the package via Composer. This package requires Laravel 10 or higher.

composer require gehrisandro/tailwind-merge-laravel

To customize the behavior (like prefixes or custom class groups), publish the configuration file to config/tailwind-merge.php using the following Artisan command:

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

If you use custom Tailwind classes (e.g., custom font sizes or colors) that TailwindMerge doesn't recognize, you can modify the classGroups in config/tailwind-merge.php. This allows you to define how custom classes should conflict and resolve.

Example: Adding a custom font size group

// config/tailwind-merge.php
return [
    'classGroups' => [
        'font-size' => [
            ['text' => ['very-large']]
        ],
    ],
];

If your Tailwind CSS configuration uses a prefix, you must update TailwindMerge to recognize it. You can do this via the config/tailwind-merge.php file or the TAILWIND_MERGE_PREFIX environment variable.

Environment Variable:

TAILWIND_MERGE_PREFIX=tw-

You can publish the package configuration file to your application's config directory using the following command:

php artisan vendor:publish --tag=tailwind-merge-config

(Note: While the exact tag isn't explicitly named in the code, the provider uses publishes to map the config file to config_path('tailwind-merge.php').)

The configuration is loaded via config('tailwind-merge', []) and is used to initialize the TailwindMerge instance.

Outside of Blade components or directives, you can merge classes using the TailwindMerge Facade or the twMerge global helper.

Using the Facade

use TailwindMerge\
Laravel\Facades\TailwindMerge;

TailwindMerge::merge('w-10 h-10 rounded-full bg-red-500 bg-blue-500');

Using the Helper

twMerge('w-10 h-10 rounded-full bg-red-500 bg-blue-500');

use TailwindMerge\Laravel\Facades\TailwindMerge;

TailwindMerge::merge('w-10 h-10 rounded-full bg-red-500 bg-blue-500');

The package provides a @twMerge directive for use directly in Blade views. It accepts a single string or multiple arguments.

{{-- Single argument --}}
@twMerge('w-10 h-10 rounded-full bg-red-500 bg-blue-500')

{{-- Multiple arguments --}}
@twMerge('w-10 h-10 rounded-full bg-red-500', 'bg-blue-500')

You can rename this directive or disable it in config/tailwind-merge.php using the blade_directive key.

The package allows you to use a Blade directive to merge Tailwind classes directly in your templates. By default, the directive name is @twMerge.

You can customize the directive name in your config/tailwind-merge.php file using the blade_directive key. If set to null, the directive will not be registered.

<div @twMerge('bg-red-500 p-4', 'bg-blue-500')></div>

The TailwindMerge facade provides a static interface to the underlying Tailwind Merge utility. You can use the merge method to resolve class conflicts by passing multiple strings of Tailwind CSS classes as arguments. It returns a single string containing the merged classes with conflicts resolved.

use TailwindMerge\Laravel\Facades\TailwindMerge;

$merged = TailwindMerge::merge('px-2 py-1', 'p-4', 'text-red-500 text-blue-500');
// Result will have conflicts resolved based on Tailwind Merge logic