tailwind-merge

What is tailwind-merge?

The tailwind-merge npm package is a utility for combining and deduplicating Tailwind CSS classes. It helps developers to programmatically merge class strings while avoiding conflicts and redundancies, ensuring the final class string is optimized for use.

What are tailwind-merge's main functionalities?

Merging Tailwind CSS classes

This feature allows you to merge multiple class strings into one, automatically resolving conflicts by using the last occurrence of a conflicting class.

"twMerge('p-4 font-bold', 'p-2 text-center') // 'p-2 font-bold text-center'"

Removing Tailwind CSS classes

This feature enables you to remove specific classes from a string by prefixing the class with a minus sign.

"twMerge('p-4 font-bold', '-p-4') // 'font-bold'"

Handling arbitrary values

Tailwind-merge can handle arbitrary values in class names, allowing you to merge classes with custom values effectively.

"twMerge('p-[30px]', 'p-4') // 'p-4'"

Handling variants and groups

The package can also manage Tailwind's variants and groups, ensuring that the correct specificity is maintained when merging classes with variants.

"twMerge('hover:bg-black', 'hover:bg-white') // 'hover:bg-white'"

Other packages similar to tailwind-merge

classnames

The classnames package is a popular utility for conditionally joining class names together. It's not Tailwind-specific, but it's often used in projects to manage dynamic class strings. Unlike tailwind-merge, it does not deduplicate or resolve conflicts specific to Tailwind CSS.

clsx

clsx is an alternative to classnames with a similar API and is used for constructing class strings conditionally. Like classnames, it does not offer Tailwind-specific deduplication or conflict resolution.

README

tailwind-merge

Utility function to efficiently merge Tailwind CSS classes in JS without style conflicts.

import { twMerge } from 'tailwind-merge'

twMerge('px-2 py-1 bg-red hover:bg-dark-red', 'p-3 bg-[#B91C1C]')
// → 'hover:bg-dark-red p-3 bg-[#B91C1C]'

• Supports Tailwind v4.0 up to v4.1 (if you use Tailwind v3, use tailwind-merge v2.6.0)
• Works in all modern browsers and maintained Node versions
• Fully typed
• Check bundle size on Bundlephobia

Get started

• What is it for
• When and how to use it
• Features
• Limitations
• Configuration
• Recipes
• API reference
• Writing plugins
• Versioning
• Contributing
• Similar packages