Download the PHP package kalel1500/laravel-tailwind-merge without Composer

[!NOTE] This project is a fork from tailwind-merge by Sandro Gehri.

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 v4.0 up to v4.2

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 12

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

Optionally, publish the configuration file:

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:

Finally, you may use TailwindMerge in various places like your Blade components:

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

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

Usage

For in depth documentation and general PHP examples, take a look at the tales-from-a-dev/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:

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

This will render the following HTML:

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 TailwindMerge you can merge classes on multiple elements by using twMergeFor():

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

This will render the following HTML:

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

Use Laravel Blade Directive

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

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

Helper Method

More usage examples

Take a look at the TailwindMerge for PHP repository.

Configuration

This package provides two types of configuration:

• merge_config: Controls how Tailwind classes are merged
• cache: Controls Laravel-specific caching behavior

Modify merge process

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

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

By default, TailwindMerge 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.

All Tailwind Merge-related configuration must now be defined inside the merge_config key in your config file.

If TailwindMerge is not able to merge your classes properly, you can modify the merge process by customizing existing class groups or adding new ones.

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

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

Cache configuration

You can configure caching behavior using the cache key:

Or using environment variables:

• enabled: Enable or disable caching entirely.
• store: The cache store to use. If null, the default store is used.

Note

By default, this package uses the file cache store instead of Laravel's default.

This is intentional, as Tailwind Merge generates a high number of small cache entries. Using the database driver may lead to performance issues and excessive database queries.

How it works internally

When using the file store, the package automatically maps it to a dedicated cache store named file_tw_merge.

This store uses a separate directory:

This ensures:

• Tailwind Merge cache entries are isolated from your application's main cache
• Your default cache store remains clean and easier to debug
• Better performance compared to database-based caching

You can still override this behavior by explicitly setting another store or using null to fallback to Laravel's default cache store.

Custom cache store

If you want full control, you can define your own cache store in config/cache.php and reference it here.

Laravel TailwindMerge is an open-sourced software licensed under the MPL-2.0.