How to extend TailwindMerge for borderWidth?

[nareshbhatia]

In my tailwind.config.js, I have extended borderWidth like this:

borderWidth: {
  sm: 'var(--border-width-sm)',
  md: 'var(--border-width-md)',
}

Now if I use a class like border-b-sm without twMerge, it works just fine. If I include twMerge, it "swallows" that style and does not return it in the output.

I tried to extend twMerge like this, but it still swallows the style:

const twMerge = extendTailwindMerge({
  // @ts-expect-error suppress type error ts(2353) TODO: fix
  theme: {
    borderWidth: ['sm', 'md'],
  },
});

What am I doing wrong?

P.S. I am getting a typescript error when using the theme property with extendTailwindMerge:

Object literal may only specify known properties, and 'theme' does not exist in type 'CreateConfigSubsequent | ConfigExtension<DefaultClassGroupIds, DefaultThemeGroupIds>'.ts(2353)

[dcastil]

Hey @nareshbhatia! 👋

You need to wrap your config in either an extend (or override) object. This config should work:

const twMerge = extendTailwindMerge({
  extend: {
    theme: {
      borderWidth: ['sm', 'md'],
    },
  },
});

[nareshbhatia]

Ah, missed that little extend detail. Thank you so much for your help, @dcastil.

[sebalaini]

this is still an issue in "tailwind-merge": "^3.0.1"

This is my config:

import { extendTailwindMerge } from 'tailwind-merge'

export const customTwMerge = extendTailwindMerge({
  extend: {
    theme: {
      spacing: ['0', 'xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl', '4xl', 'auto'],
      borderWidth: ['0', 'sm', 'md', 'lg'],
      borderRadius: ['none', 'sm', 'md', 'lg', 'xl', 'round', 'pill'],
    },
  },
})

Both Border keys return an error:

Object literal may only specify known properties, and 'borderXXX' does not exist in type 'Partial<ThemeObject<DefaultThemeGroupIds>>'.ts(2353)

[sebalaini]

thanks for the clarification :)

[goodpixels]

I've stumbled upon this thread because I can't seem to configure my twMerge correctly.

I don't really understand your answer @dcastil . Does it mean I have to declare all custom border-width utilities under the classGroups object? Like, explicitly list all border-w, border-w-l, border-w-t, etc.? Or am I missing something here? Here's my tailwind.config.ts:

theme: {
    extend: {
      borderWidth: {
        xs: "10px",
        sm: "20px",
        md: "40px",
        lg: "60px",
        xl: "120px",
      },

How would I add these to tailwind-merge.ts configuration?

As a side note, twMerge is great, but configuration is absolutely AWFUL. It really should pick up the values from tailwind.config.ts, rather than have me redeclare everything twice. The biggest issue is that the documentation about configuring twMerge() is very poor and unclear. It might make sense to you, as the author of the package, but unfortunately it's not easy to digest for the actual user. It would be great if you could simplify the configuration or at least make the documentation more accessible and easy to understand.

This is not a go at you @dcastil , as the package is great, but it really needs to be simpler to configure so more people can use it.

[dcastil]

Hey @goodpixels! 👋

tailwind-merge v3 optimizes for the CSS config of Tailwind CSS v4 (where there is no border width theme variable namespace) which means there is more pain for JS config users. You're correct that with your custom border width scale you'll need to modify all the right class groups which are all border-w-* IDs.

This is the config you'd need:

import { extendTailwindMerge } from 'tailwind-merge'

const borderWidths = ['xs', 'sm', 'md', 'lg', 'xl']

const twMerge = extendTailwindMerge({
    extend: {
        classGroups: {
            'border-w': [{ border: borderWidths }],
            'border-w-x': [{ 'border-x': borderWidths }],
            'border-w-y': [{ 'border-y': borderWidths }],
            // …
        }
    }
})

Since you can represent any border width with a px unit in Tailwind CSS v4, I'd recommend to use the new syntax instead of configuring a custom scale in the config, then you don't need to configure tailwind-merge. E.g. you can use border-10 which works out of the box instead of the custom border-xs. And if you want to reduce your options to a certain set, you can do that in JS land as well:

const border = {
    xs: 'border-10',
    sm: 'border-20',
    // …
}

And yes, I agree that the configuring tailwind-merge is not great, especially if your Tailwind config deviates a lot from the default. Making this better is a bigger effort though since tailwind-merge has tighter requirements regarding bundle size and runtime perf than Tailwind CSS itself (buildtime vs. browser runtime environment). And unfortunately I don't have the time and access to some important APIs to build a more sophisticated Tailwind plugin to configure tailwind-merge automatically. But who knows, maybe it will happen some time in the future.

Regarding documentation: What were the biggest issues you ran into there? That would help me a lot in figuring out where to invest my time into.

[goodpixels]

Amazing reply, thank you very much for the time taken to answer me.

I have since managed to configure my twMerge, and it's working as expected, but the configuration is not intuitive and requires a lot of repetition.

I don't know the inner workings of Tailwind itself or Tailwind Merge, but I really am struggling to understand why is it not possible to just pick up the array of key names from the tailwind.config.ts file? The actual values don't really matter, it's just about the key names.

Tailwind 4, while nice, is not going to become mainstream for a looong time, everyone with commercial projects (probably the majority of Tailwind's users) is still on version 3 and that's not going to change soon, so all the benefits of 4 don't apply to the vast number of users. Maybe I'm a bit of a dreamer, but I would love to just install tailwind-merge and read my configuration from my Tailwind 3 config...

The biggest issue with the current documentation is lack of real-world examples.

Most users won't have overly complex tailwind.config.ts configurations, they will most likely adjust text sizing, border widths, some colours, etc. These options should be really easy to configure in your package too. Configuration intailwind.config.ts takes seconds, but twMerge expects different key names, different object structure and doesn't really provide an example repository of common scenarios.

[dcastil]

Thanks for the input! By the way tailwind-merge v3 is only intended to be used with Tailwind CSS v4. If you use Tailwind CSS v3, you should use tailwind-merge v2. The reason for this is that there were breaking changes necessary in tailwind-merge to support Tailwind v4.

In tailwind-merge v2 you can use the following config and don't need to specify all the class groups individually:

import { extendTailwindMerge } from 'tailwind-merge' // v2.6.0

const twMerge = extendTailwindMerge({
    extend: {
        theme: {
            // See https://github.com/dcastil/tailwind-merge/blob/v2.6.0/docs/configuration.md#theme
            borderWidth: ['xs', 'sm', 'md', 'lg', 'xl']
        }
    }
})