- How do I install and use tailwind-merge in Laravel Blade components?
- Install it with composer require gehrisandro/tailwind-merge-laravel. There are no migrations or service wiring to do; the package registers a thin service provider that exposes a TailwindMerge facade, a twMerge() helper, an @twMerge Blade directive, and a twMerge() macro on Laravel's ComponentAttributeBag. You can optionally publish the config file if you need to customise class groups.
- Which Tailwind CSS versions does gehrisandro/tailwind-merge-laravel support?
- The package documents support for Tailwind CSS v3.0 through v3.3, and package version 1.1.0 added support for Tailwind v3.4. Nothing in the documentation evidences support for Tailwind v4, whose CSS-first configuration and revised utility semantics would likely break the package's hardcoded class-group taxonomy. Treat the package as a constraint on how fast you can upgrade Tailwind.
- Which Laravel versions are supported?
- The README states Laravel 10 as the requirement, and compatibility releases for later Laravel majors such as 11, 12 and 13 appear to be community- or bot-driven rather than part of an announced roadmap. Because of that reactive maintenance pattern, check the release notes and test suite status for your exact Laravel version before adopting. The package itself is a presentation-layer utility with no database, queue or cache dependencies, so Laravel compatibility is mostly about the service provider and Blade APIs.
- How is this different from Laravel's $attributes->merge(['class' => '...'])?
- Laravel's built-in merge only concatenates class strings, so passing px-4 and later px-6 leaves both in the class attribute and lets CSS source order decide the winner. TailwindMerge resolves conflicts deterministically using a class-group taxonomy, so the last class always wins. The README explicitly lists $attributes->merge(['class' => '...']) as an unsupported case, which means adopting the package is partly an editorial change: you need to replace the familiar idiom and enforce the new convention in review.
- How do I configure custom Tailwind classes like custom font sizes, colours or spacing?
- Publish the config file and add or adjust classGroups entries for anything that deviates from Tailwind's defaults, such as custom font sizes, colour names that collide with utility names, custom spacing scales, and prefixes (there is also a TAILWIND_MERGE_PREFIX environment variable). Be aware that a missing or wrong class group produces a silent mis-merge: a class the developer intended to keep is dropped with no exception thrown. Mitigate with visual regression or contract tests around your component library.
- What are the twMerge() helper, the @twMerge directive and the TailwindMerge facade?
- All three are entry points to the same merge engine. The twMerge() helper and TailwindMerge::merge() are useful anywhere in PHP, while the @twMerge Blade directive keeps templates readable. Each one takes a list of class strings and returns a single string where conflicting utilities are resolved in favour of the class that appears last, so order in your template matters.
- Does this package work with Tailwind CSS v4?
- Based on the available documentation, no. The README covers Tailwind v3.0 to v3.3, with a later release adding v3.4, and nothing indicates v4 support. Because v4 changes configuration and utility semantics, a hardcoded class-group taxonomy is exactly the kind of code that breaks. If you plan to move to Tailwind v4, confirm the maintainer's roadmap first, or be prepared to own that work yourself.
- What do twMergeFor() and withoutTwMergeClasses() do on the component attribute bag?
- twMergeFor('name', '...') merges classes for a named attribute inside the bag, which is how you handle components that forward classes to more than one element rather than a single root. withoutTwMergeClasses() strips the package's merge-related attributes from the bag so they are not rendered into your HTML. Apply it to the root bag; forgetting to do so is harmless but leaks class:icon="..." style attributes into the markup.
- Why are extra attributes like class:icon appearing in my rendered HTML?
- Those are the merge control attributes carried on the ComponentAttributeBag. They render as normal HTML attributes unless you call withoutTwMergeClasses() on the root bag before outputting $attributes. It is an easy mistake to make once and produces noisy but non-breaking markup, so add it to your component boilerplate and check it in review.
- Is it safe to use in production, and what happens if the package is abandoned?
- The package is a thin, MIT-licensed Laravel wrapper around gehrisandro/tailwind-merge-php, with a single maintainer and modest adoption signals, so bus factor is a fair concern. Exit cost is genuinely low: worst case you depend on the PHP core directly, vendor it, or fork it. The bigger production risk is silent mis-merging under custom Tailwind configuration, which needs class-group configuration plus visual tests.