gehrisandro / tailwind-merge-laravel by gehrisandro

TailwindMerge for Laravel allows you to merge multiple Tailwind CSS classes and automatically resolves 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.

A Laravel / PHP port of tailwind-merge by dcastil.

Supports Tailwind v3.0 up to v3.3.

If you find this package helpful, please consider sponsoring the maintainer:

• Sandro Gehri: github.com/sponsors/gehrisandro

Attention: This package is still in early development.

If you are NOT using Laravel, you can use the TailwindMerge for PHP directly.

Table of Contents

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

Get Started

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 various places like your Blade components:

// circle.blade.php
<div {{ $attributes->twMerge('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

Usage

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

Use in Laravel Blade Components

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->twMerge('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.

Use Laravel Blade Directive

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

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

// or multiple arguments
@twMerge('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' => 'customTwMerge',
];

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

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

Everywhere else in Laravel

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

Facade

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

Helper Method

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

More usage examples

Take a look at the TailwindMerge for PHP repository.

Configuration

Note: To do

Custom Tailwind Config

Note: To do

Contributing

Thank you for considering contributing to TailwindMerge for Laravel! The contribution guide can be found in the CONTRIBUTING.md file.

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