README

TailwindClassMerge 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:

Devanox Private Limited: github.com/sponsors/devanoxltd

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

Get Started
Usage
Configuration
- Custom Tailwind Config
Contributing

Get Started

Requires Laravel 10

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

composer require devanoxltd/tailwind-class-merge-laravel

Optionally, publish the configuration file:

php artisan vendor:publish --provider="TailwindClassMerge\Laravel\TailwindClassMergeServiceProvider"

This will create a config/tailwind-class-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 TailwindClassMerge in various places like your Blade components:

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

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

use TailwindClassMerge\Laravel\Facades\TailwindClassMerge;

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

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

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

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

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

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

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

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

// non tailwind classes
TailwindClassMerge::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:

TailwindClassMerge::merge('h-10 h-20'); // h-20
TailwindClassMerge::merge(['h-10', 'h-20']); // h-20
TailwindClassMerge::merge(['h-10', 'h-20'], 'h-30'); // h-30
TailwindClassMerge::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 devanoxltd/tailwind-class-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->tailwindClass('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 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.

Merge classes on multiple elements

By default Laravel allows you to only merge classes in one place. But with TailwindClassMerge you can merge classes on multiple elements by using forAttributes():

// button.blade.php
<button {{ $attributes->withoutForAttributes()->tailwindClass('p-2 bg-gray-900 text-white') }}>
    <svg {{ $attributes->forAttributes('icon')->tailwindClass('h-4 text-gray-500') }} viewBox="0 0 448 512"><path d="..."/></svg>

    {{ $slot }}
</button>

You can now specify additional classes for the button and the svg icon:

// your-view.blade.php
<x-button class="bg-blue-900" component:icon:class="text-blue-500">
  Click Me
</x-button>

This will render the following HTML:

<button class="p-2 bg-blue-900 text-white">
  <svg class="h-4 text-blue-500" viewBox="0 0 448 512"><path d="..."/></svg>

  Click Me
</button>

Note: Use withoutForAttributes() on your main attributes bag, otherwise all component:xyz:class attributes will be rendered in the output.

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

// config/tailwind-class-merge.php
return [
    'attribute_prefix' => 'component:',
];

Use Laravel Blade Directive

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

@tailwindClass('w-10 h-10 rounded-full bg-red-500 bg-blue-500') // class="w-10 h-10 rounded-full bg-blue-500"

// or multiple arguments
@tailwindClass('w-10 h-10 rounded-full bg-red-500', 'bg-blue-500') // class="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-class-merge.php configuration file:

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

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

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

Everywhere else in Laravel

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

Facade

use TailwindClassMerge\Laravel\Facades\TailwindClassMerge;

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

Helper Method

tailwindClass('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 TailwindClassMerge for PHP repository.

Configuration

If you are using Tailwind CSS without any extra config, you can use TailwindClassMerge right away. And stop reading here.

If you're using a custom Tailwind config, you may need to configure TailwindClassMerge as well to merge classes properly.

By default TailwindClassMerge is configured in a way that you can still use it if all the following apply to your Tailwind config:

Only using color names which don't clash with other Tailwind class names
Only deviating by number values from number-based Tailwind classes
Only using font-family classes which don't clash with default font-weight classes
Sticking to default Tailwind config for everything else

If some of these points don't apply to you, you need to customize the configuration.

Configure Prefix

You can configure the prefix directly in the config/tailwind-class-merge.php configuration file or by setting the environment variable:

TAILWIND_MERGE_PREFIX=tw-

Modify merge process

If TailwindClassMerge is not able to merge your changes properly you can modify the merge process by modifying existing class groups or adding new class groups.

For example, if you want to add a custom font size of "very-large":

// config/tailwind-class-merge.php

return [
  'classGroups' => [
      'font-size' => [
          ['text' => ['very-large']]
      ],
  ],
];

For a more detailed explanation of the configuration options, visit the original package documentation.

Contributing

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

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

devanoxltd / tailwind-class-merge-laravel

Maintainers

Details