dcastil/tailwind-merge
Tailwind Merge
tailwind-merge is a utility library that resolves conflicting Tailwind CSS class strings when combining multiple sets of classes. It automatically detects and removes conflicting utility classes, keeping only the last class from each group that modifies the same CSS property, while preserving non-conflicting and non-Tailwind classes unchanged.
The library handles complex conflict scenarios including modifier-order resolution, arbitrary value type detection, postfix modifier semantics, and asymmetric conflicts where one class group removes preceding classes from other groups but not vice versa. It supports third-party Tailwind plugins through extensible configuration, allowing custom class groups, conflict rules, and validators to be merged into the default setup. Users can build fully custom merge functions from scratch or extend the default configuration with overrides and additions.
Performance is optimized through deferred initialization that delays expensive setup until the first merge call, internal data structure reuse across calls, and an LRU cache that stores recent merge results to skip redundant computation on repeated inputs. The library also provides conditional class joining without conflict resolution as a lightweight alternative for internal component styles.
Features
- Arbitrary Value Class Mergers - Merges classes with arbitrary values, automatically detecting their type and resolving conflicts.
- Tailwind CSS Conflict Resolvers - Resolves conflicting Tailwind utility classes by keeping only the last class from each group that modifies the same CSS property.
- Modifier Conflict Resolvers - Resolves conflicts between classes with modifiers, including stacked modifiers, respecting modifier order rules.
- Modifier-Order Conflict Resolvers - Resolves conflicts between classes with stacked modifiers by respecting Tailwind's modifier order rules.
- Tailwind Class - Merges multiple Tailwind CSS class strings into a single string, handling conditional values and nested arrays without style conflicts.
- CSS Arbitrary Value Type Detectors - Provides heuristics to infer CSS types from arbitrary bracket values, enabling correct conflict resolution.
- Class String Joiners - Provides a utility that accepts multiple arguments, conditional values, and nested arrays to build a single merged class string.
- Shorthand Conflict Resolvers - Handles complex conflicts like between shorthand and longhand properties or opposite display values.
- Prop-Based Utility Styling - Provides a utility that applies arbitrary Tailwind utilities via className props, eliminating the need for explicit style props.
- Component Style Overrides - Enables overriding component styles through className props instead of defining every styling option as a prop.
- Arbitrary CSS Property Mergers - Merges classes with arbitrary CSS properties while acknowledging limitations in conflict resolution.
- Ambiguous Arbitrary Value Disambiguators - Uses explicit labels to disambiguate arbitrary value classes that match multiple Tailwind patterns.
- Custom Merge Function Builders - Allows building a fully custom merge function from scratch to tree-shake default configurations.
- Asymmetric Conflict Definitions - Sets up one-way conflicts where a class group removes preceding classes from other groups but not vice versa.
- Custom Class Group Configurations - Allows users to define custom groups of conflicting Tailwind classes for the merge function.
- Non-Conflicting Refinement Preservers - Preserves multiple classes that refine the same property without conflict during merging.
- Non-Tailwind Class Preservers - Keeps any class that is not a Tailwind utility class unchanged during merging.
- Merge Configuration Overrides - Creates custom merge functions by extending or overriding the default Tailwind configuration with custom theme values and class groups.
- Default Merge Configuration Extenders - Creates custom merge functions by extending the default Tailwind configuration with overrides and additions.
- Tailwind Merge Configuration Extenders - Provides an API to extend the default merge configuration with custom theme values and class groups.
- Tailwind Plugin Integrations - Supports third-party Tailwind plugins through extensible configuration, allowing custom class groups and conflict rules to be merged.
- CSS Class Value Validators - Provides validator functions to check if a class value matches a specific CSS type for correct conflict resolution.
- Merge Configuration Extensions - Allows extending the default merge configuration with custom class groups, theme values, and conflict rules for third-party plugins.
- Merge Plugin Integrations - Extends the merge function to support third-party Tailwind CSS plugin classes by adding custom class groups and conflict rules.
- Non-Tailwind Class Preservers - Preserves any class that is not a Tailwind utility class unchanged during merging.
- Conflict-Free Joiners - Provides a conflict-free class joining mode as a lightweight alternative to the full conflict resolver.
- Arbitrary Variant Class Mergers - Merges classes with arbitrary variants while acknowledging limitations in conflict resolution.
- Third-Party Plugin Class Mergers - Integrates third-party Tailwind plugin classes into the merge function by adding custom class groups.
- Conditional Joining - Ships a lightweight conditional class joining utility as an alternative to clsx for internal component styles.
- Multi-Level Style Override Passers - Passes style overrides through nested component layers without breaking existing styles.
- One-Way Conflict Definitions - Ships configuration for one-way class group conflicts, enabling precise asymmetric override rules.
- Tailwind Merge Configuration Builders - Builds a merge function from scratch with full control over class groups, conflicts, and modifiers.
