Reference to all exports of tailwind-merge.
function twMerge(
...classLists: Array<string | undefined | null | false | 0 | typeof classLists>
): stringDefault function to use if you're using the default Tailwind config or are close enough to the default config. Check out basic usage for more info.
If twMerge doesn't work for you, you can create your own custom merge function with extendTailwindMerge.
function twJoin(
...classLists: Array<string | undefined | null | false | 0 | typeof classLists>
): stringFunction to join className strings conditionally without resolving conflicts.
twJoin(
'border border-red-500',
hasBackground && 'bg-red-100',
hasLargeText && 'text-lg',
hasLargeSpacing && ['p-2', hasLargeText ? 'leading-8' : 'leading-7'],
)It is used internally within twMerge and a direct subset of clsx. If you use clsx or classnames to apply Tailwind classes conditionally and don't need support for object arguments, you can use twJoin instead, it is a little faster and will save you a few hundred bytes in bundle size.
Why no object support? Read here.
function getDefaultConfig(): ConfigFunction which returns the default config used by tailwind-merge. The tailwind-merge config is different from the Tailwind config. It is optimized for small bundle size and fast runtime performance because it is expected to run in the browser.
function fromTheme(key: string): ThemeGetterFunction to retrieve values from a theme scale, to be used in class groups.
fromTheme doesn't return the values from the theme scale, but rather another function which is used by tailwind-merge internally to retrieve the theme values. tailwind-merge can differentiate the theme getter function from a validator because it has a isThemeGetter property set to true.
It can be used like this:
extendTailwindMerge({
theme: {
'my-scale': ['foo', 'bar']
},
classGroups: {
'my-group': [{ 'my-group': [fromTheme('my-scale'), fromTheme('spacing')] }]
'my-group-x': [{ 'my-group-x': [fromTheme('my-scale')] }]
}
})function extendTailwindMerge(
configExtension: Partial<Config>,
...createConfig: Array<(config: Config) => Config>
): TailwindMerge
function extendTailwindMerge(...createConfig: Array<(config: Config) => Config>): TailwindMergeFunction to create merge function with custom config which extends the default config. Use this if you use the default Tailwind config and just extend it in some places.
Note The function
extendTailwindMergecomputes a large data structure based on the config passed to it. I recommend to call it only once and store the result in a top-level variable instead of calling it inline within another repeatedly called function.
You provide it a configExtension object which gets merged with the default config.
const customTwMerge = extendTailwindMerge({
cacheSize: 0, // ← Disabling cache
// ↓ Optional prefix from TaiLwind config
prefix: 'tw-',
// ↓ Optional separator from TaiLwind config
separator: '_',
// ↓ Add values to existing theme scale or create a new one
// Not all theme keys form the Tailwind config are supported by default.
theme: {
spacing: ['sm', 'md', 'lg'],
},
// ↓ Here you define class groups
classGroups: {
// ↓ The `foo` key here is the class group ID
// ↓ Creates group of classes which have conflicting styles
// Classes here: foo, foo-2, bar-baz, bar-baz-1, bar-baz-2
foo: ['foo', 'foo-2', { 'bar-baz': ['', '1', '2'] }],
// ↓ Functions can also be used to match classes.
// Classes here: qux-auto, qux-1000, qux-1001,…
bar: [{ qux: ['auto', (value) => Number(value) >= 1000] }],
baz: ['baz-sm', 'baz-md', 'baz-lg'],
},
// ↓ Here you can define additional conflicts across different groups
conflictingClassGroups: {
// ↓ ID of class group which creates a conflict with…
// ↓ …classes from groups with these IDs
// In this case `twMerge('qux-auto foo') → 'foo'`
foo: ['bar'],
},
// ↓ Here you can define conflicts between the postfix modifier of a group and a different class group.
conflictingClassGroupModifiers: {
// ↓ ID of class group whose postfix modifier creates a conflict with…
// ↓ …classes from groups with these IDs
// In this case `twMerge('qux-auto baz-sm/1000') → 'baz-sm/1000'`
baz: ['bar'],
},
})Additionally, you can pass multiple createConfig functions (more to that in createTailwindMerge) which is convenient if you want to combine your config with third-party plugins.
const customTwMerge = extendTailwindMerge({ … }, withSomePlugin)If you only use plugins, you can omit the configExtension object as well.
const customTwMerge = extendTailwindMerge(withSomePlugin)function createTailwindMerge(
...createConfig: [() => Config, ...Array<(config: Config) => Config>]
): TailwindMergeFunction to create merge function with custom config. Use this function instead of extendTailwindMerge if you don't need the default config or want more control over the config.
Note The function
createTailwindMergecomputes a large data structure based on the config passed to it. I recommend to call it only once and store the result in a top-level variable instead of calling it inline within another repeatedly called function.
You need to provide a function which resolves to the config tailwind-merge should use for the new merge function. You can either extend from the default config or create a new one from scratch.
// ↓ Callback passed to `createTailwindMerge` is called when
// `customTwMerge` gets called the first time.
const customTwMerge = createTailwindMerge(() => {
const defaultConfig = getDefaultConfig()
return {
cacheSize: 0,
classGroups: {
...defaultConfig.classGroups,
foo: ['foo', 'foo-2', { 'bar-baz': ['', '1', '2'] }],
bar: [{ qux: ['auto', (value) => Number(value) >= 1000] }],
baz: ['baz-sm', 'baz-md', 'baz-lg'],
},
conflictingClassGroups: {
...defaultConfig.conflictingClassGroups,
foo: ['bar'],
},
conflictingClassGroupModifiers: {
...defaultConfig.conflictingClassGroupModifiers,
baz: ['bar'],
},
}
})Same as in extendTailwindMerge you can use multiple createConfig functions which is convenient if you want to combine your config with third-party plugins. Just keep in mind that the first createConfig function does not get passed any arguments, whereas the subsequent functions get each passed the config from the previous function.
const customTwMerge = createTailwindMerge(getDefaultConfig, withSomePlugin, (config) => ({
// ↓ Config returned by `withSomePlugin`
...config,
classGroups: {
...config.classGroups,
mySpecialClassGroup: [{ special: ['1', '2'] }],
},
}))But don't merge configs like that. Use mergeConfigs instead.
function mergeConfigs(baseConfig: Config, configExtension: Partial<Config>): ConfigHelper function to merge multiple tailwind-merge configs. Properties with the value undefined are skipped.
const customTwMerge = createTailwindMerge(getDefaultConfig, (config) =>
mergeConfigs(config, {
override: {
classGroups: {
// ↓ Overriding existing class group
shadow: [{ shadow: ['100', '200', '300', '400', '500'] }],
},
}
extend: {
// ↓ Adding value to existing class group
animate: ['animate-shimmer'],
// ↓ Adding new class group
prose: [{ prose: ['', validators.isTshirtSize] }],
},
}),
)interface Validators {
isLength(value: string): boolean
isArbitraryLength(value: string): boolean
isNumber(value: string): boolean
isInteger(value: string): boolean
isPercent(value: string): boolean
isArbitraryValue(value: string): boolean
isTshirtSize(value: string): boolean
isArbitrarySize(value: string): boolean
isArbitraryPosition(value: string): boolean
isArbitraryUrl(value: string): boolean
isArbitraryNumber(value: string): boolean
isArbitraryShadow(value: string): boolean
isAny(value: string): boolean
}An object containing all the validators used in tailwind-merge. They are useful if you want to use a custom config with extendTailwindMerge or createTailwindMerge. E.g. the classGroup for padding is defined as
const paddingClassGroup = [{ p: [validators.isLength] }]A brief summary for each validator:
isLengthchecks whether a class part is a number (3,1.5), a fraction (3/4), or one of the stringspx,fullorscreen.isArbitraryLengthchecks for arbitrary length values ([3%],[4px],[length:var(--my-var)]).isNumberchecks for numbers (3,1.5)isArbitraryNumberchecks whether class part is an arbitrary value which starts withnumber:or is a number ([number:var(--value)],[450]) which is necessary for font-weight and stroke-width classNames.isIntegerchecks for integer values (3).isPercentchecks for percent values (12.5%) which is used for color stop positions.isArbitraryValuechecks whether the class part is enclosed in brackets ([something])isTshirtSizechecks whether class part is a T-shirt size (sm,xl), optionally with a preceding number (2xl).isArbitrarySizechecks whether class part is an arbitrary value which starts withsize:([size:200px_100px]) which is necessary for background-size classNames.isArbitraryPositionchecks whether class part is an arbitrary value which starts withposition:([position:200px_100px]) which is necessary for background-position classNames.isArbitraryUrlchecks whether class part is an arbitrary value which starts withurl:orurl(([url('/path-to-image.png')],url:var(--maybe-a-url-at-runtime)]) which is necessary for background-image classNames.isArbitraryShadowchecks whether class part is an arbitrary value which starts with the same pattern as a shadow value ([0_35px_60px_-15px_rgba(0,0,0,0.3)]), namely with two lengths separated by a underscore.isAnyalways returns true. Be careful with this validator as it might match unwanted classes. I use it primarily to match colors or when I'm certain there are no other class groups in a namespace.
interface Config { … }TypeScript type for config object. Useful if you want to build a createConfig function but don't want to define it inline in extendTailwindMerge or createTailwindMerge.
type ClassNameValue = string | null | undefined | 0 | false | ClassNameValue[]TypeScript type for arguments accepted by twMerge and twJoin. You might want to use it if you wrap any of those with your own function.
function myWrappedTwMerge(...args: ClassNameValue[]) {
doSomething()
return twMerge(...args)
}Next: Writing plugins
Previous: Recipes