Tailwind CSS Merge for Laravel is a Laravel package that allows you to merge multiple Tailwind CSS classes by automatically resolving conflicts between classes by removing classes conflicting with a class defined later. This is especially helpful when you want to override Tailwind CSS classes in your Blade components.
Essentially, a Laravel port of tailwind-merge by dcastil.

Supports Tailwind v3.0 up to v3.3.

Attention: This package is still in development and not ready for production use.
At the moment only this README is publicly available. The package will be released soon. Star this repository or follow me on Twitter to get notified when the package is released.

• Get Started
• Usage
  • Laravel Blade Components
  • Laravel Blade Directive
  • Everywhere else in Laravel
• Configuration
  • Custom Tailwind Config
• Contributing

Requires Laravel 10

First, install TailwindMerge for Laravel via the Composer package manager:

composer require gehrisandro/tailwind-merge-laravel

Next, publish the configuration file:

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

This will create a config/tailwind-merge.php configuration file in your project, which you can modify to your needs using environment variables. For more information, see the Configuration section.

TAILWIND_MERGE_PREFIX=tw-

Finally, you may use TailwindMerge in your Blade components:

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

// your-view.blade.php
<x-circle class="bg-blue-500" />

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

TailwindMerge is not only capable of resolving conflicts between basic Tailwind CSS classes, but also handles more complex scenarios:

use TailwindMerge\Laravel\Facades\TailwindMerge;

// conflicting classes
TailwindMerge::merge('block inline'); // inline
TailwindMerge::merge('pl-4 px-6'); // px-6

// non-conflicting classes
TailwindMerge::merge('text-xl text-black'); // text-xl text-black

// with breakpoints
TailwindMerge::merge('h-10 lg:h-12 lg:h-20'); // h-10 lg:h-20

// dark mode
TailwindMerge::merge('text-black dark:text-white dark:text-gray-700'); // text-black dark:text-gray-700

// with hover, focus and other states
TailwindMerge::merge('hover:block hover:inline'); // hover:inline

// with the important modifier
TailwindMerge::merge('!font-medium !font-bold'); // !font-bold

// arbitrary values
TailwindMerge::merge('z-10 z-[999]'); // z-[999] 

// arbitrary variants
TailwindMerge::merge('[&>*]:underline [&>*]:line-through'); // [&>*]:line-through

// non tailwind classes
TailwindMerge::merge('non-tailwind-class block inline'); // non-tailwind-class inline 

It's possible to pass the classes as a string, an array or a combination of both:

TailwindMerge::merge('h-10 h-20'); // h-20
TailwindMerge::merge(['h-10', 'h-20']); // h-20
TailwindMerge::merge(['h-10', 'h-20'], 'h-30'); // h-30
TailwindMerge::merge(['h-10', 'h-20'], 'h-30', ['h-40']); // h-40

For in depth documentation and general PHP examples, take a look at the gehrisandro/tailwind-merge-php repository.

Create your Blade components as you normally would, but instead of specifying the class attribute directly, use the mergeClasses method:

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

Now you can use your Blade components and pass additional classes to merge:

// your-view.blade.php
<x-circle class="bg-blue-500" />

This will now render the following HTML:

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

Note: Usage of $attributes->merge(['class' => '...']) is currently not supported due to limitations in Laravel.

The package registers a Blade directive which can be used to merge classes in your Blade views:

@mergeClasses('w-10 h-10 rounded-full bg-red-500 bg-blue-500') // w-10 h-10 rounded-full bg-blue-500

// or multiple arguments
@mergeClasses('w-10 h-10 rounded-full bg-red-500', 'bg-blue-500') // w-10 h-10 rounded-full bg-blue-500

If you want to rename the blade directive, you can do so in the config/tailwind-merge.php configuration file:

// config/tailwind-merge.php
return [
    'blade_directive' => 'customMergeClasses',
];

You could even disable the directive completely by setting it to null:

// config/tailwind-merge.php
return [
    'blade_directive' => null,
];

If you don't use Laravel Blade, you can still use TailwindMerge by using the merge method directly:

use TailwindMerge\Laravel\Facades\TailwindMerge;

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

For more examples, take a look at the gehrisandro/tailwind-merge-php repository.

Note: To be documented

Note: To be documented

Thank you for considering contributing to Tailwind Merge for PHP! The contribution guide can be found in the CONTRIBUTING.md file.

Tailwind Merge for PHP is an open-sourced software licensed under the MIT license.