What is tailwind-merge?

dcastil/tailwind-merge — explained in plain English

Analysis updated 2026-06-26

★ 5,629TypeScriptAudience · developerComplexity · 1/5Setup · easy

Mindmap

mindmap
  root((tailwind-merge))
    What it does
      Merges class strings
      Removes conflicts
      Last class wins
    Tech Stack
      TypeScript
      npm package
      Tailwind CSS
    Use Cases
      Reusable components
      Dynamic class lists
      Design tokens
    Audience
      Frontend developers
      Component authors

mindmap root((tailwind-merge)) What it does Merges class strings Removes conflicts Last class wins Tech Stack TypeScript npm package Tailwind CSS Use Cases Reusable components Dynamic class lists Design tokens Audience Frontend developers Component authors

Click or tap to explore — scroll the page freely

What do people build with it?

USE CASE 1

Merge default component classes with user-provided overrides without class conflicts in React or Vue components.

USE CASE 2

Build a reusable button that accepts a className prop and correctly resolves padding or color conflicts.

USE CASE 3

Clean up dynamically generated Tailwind class strings before rendering them to the DOM.

What is it built with?

TypeScriptTailwind CSSnpm

How does it compare?

	dcastil/tailwind-merge	kucherenko/jscpd	google/clasp
Stars	5,629	5,626	5,637
Language	TypeScript	TypeScript	TypeScript
Setup difficulty	easy	easy	easy
Complexity	1/5	2/5	2/5
Audience	developer	developer	developer

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · easy Time to first run · 5min

License information was not mentioned in the explanation.

So what is it?

tailwind-merge is a TypeScript utility that combines Tailwind CSS class strings and removes conflicting entries. It is installed as an npm package and used directly in JavaScript or TypeScript code. Tailwind CSS is a popular way of styling web pages by attaching short utility class names directly to HTML elements. A common problem occurs when building reusable components: if a parent component passes class names and the component also has its own defaults, both sets of classes end up in the rendered HTML. When two classes control the same CSS property (for example, "px-2" and "p-3" both affect padding), the browser applies whichever appears later in the stylesheet, which may not be what you intended. tailwind-merge handles this by analyzing the full list of class names, identifying which ones conflict, and returning a cleaned-up string where later or more specific classes win. In the example from the README, combining "px-2 py-1 bg-red hover:bg-dark-red" with "p-3 bg-[#B91C1C]" produces "hover:bg-dark-red p-3 bg-[#B91C1C]": the padding shorthand "p-3" replaces "px-2 py-1", and the custom background color replaces "bg-red". The library supports Tailwind v4.0 through v4.3. Users still on Tailwind v3 should use tailwind-merge v2.6.0 instead. The package is fully typed in TypeScript, so type checkers and code editors can surface errors when the merge function is called incorrectly. Separate documentation pages in the repository cover configuration, a plugin system for extending it with custom Tailwind settings, known limitations, and an API reference. The package size is tracked on Bundlephobia for anyone who wants to know its impact on a JavaScript bundle.

Copy-paste prompts

Prompt 1

Using tailwind-merge, write a React Button component that accepts a className prop and merges it with defaults like 'px-4 py-2 bg-blue-500' so the caller's classes always win.

Prompt 2

Show me how to use twMerge to combine 'p-2 text-red-500' with 'p-4' and explain which classes survive and why.

Prompt 3

Create a utility function with tailwind-merge that merges an array of conditional Tailwind class strings and removes duplicates or conflicts.

Prompt 4

Set up tailwind-merge with a custom Tailwind v4 config that includes a brand color scale so the merge function understands my custom classes.

Frequently asked questions