What's the best approach when working with custom classes?

[b-89]

Hi, after reviewing your documentation, I still wasn't sure what's the most straight forward and practical approach when working with custom Tailwind classes? We're considering creating some custom classes of commonly used patterns across our app, but it doesn't work with twMerge out of the box. Thanks ahead of time for any guidance!

[dcastil]

Hi @b-89! 👋

The best way for this is to create a file where you configure tailwind-merge with extendTailwindMerge and export your custom twMerge function, which you then use everywhere. You put all your custom classes into the object you pass as argument to extendTailwindMerge. Where exactly depends on the classes.

Do you have an example of how you want to extend the Tailwind config?

[b-89]

I was just trying to figure out if we can pull out some reusable patterns for our form elements, but still have the overriding ability provided by tailwind-merge. Ideally it would be nice if they could be picked up where Tailwind exemplifies setting them up at, but obviously it's not as easy as just saying it.

[dcastil]

Ah I got what you mean. I think if possible, I'd rather create a variable with all the Tailwind classes you want to apply for the form styles. This way you still get the reusability of these styles but don't have to change anything in tailwind-merge. Otherwise you run into the risk that someone updates the styles added to the class without updating the tailwind-merge config.

But in case you want to do it, here's how:

Let's say you create two classes input-a and input-b which both set border-radius and border-width.

First you need to create a new class group with the two classes in it (one group for both is fine since they apply the same styles). We need a unique class group ID for it, let's call it form-input. This way our tailwind-merge config looks like this:

const twMerge = extendTailwindMerge({
    classGroups: {
        'form-input': [{ input: ['a', 'b'] }]
    }
})

Now both classes are able to override each other.

But we want theses classes to also override the border radius and border width classes from Tailwind. For this we set up that the new classes are conflicting with those other class groups.

First, we need to figure out the class group IDs for those classes. We can do this here and see that they are rounded, rounded-t, rounded-r, etc. for border-radius and border-w, border-w-x, border-w-y, etc. for border-width.

Now we need to add all the class group IDs which we want to remove if any of the form-input classes appears. We can do this with conflictingClassGroups so that our tailwind-merge config looks like this:

const twMerge = extendTailwindMerge({
    classGroups: {
        'form-input': [{ input: ['a', 'b'] }]
    },
    conflictingClassGroups: {
        'form-input': [
            'rounded',
            'rounded-t',
            'rounded-r',
            …
            'border-w',
            'border-w-x',
            'border-w-y',
            …
        ]
    }
})

Now tailwind-merge will also remove the border-radius and border-width classes if a form-input class appears in a string.

Hope this example brings some clarity. Let me know if something is still unclear.