How to merge custom utility classes (which change multiple properties)?

[bengry]

I've added a couple of useful utility classes to my tailwind project: vstack and hstack, these basically are:

.vstack {
  display: flex;
  flex-direction: column;
}

.vstack-1 {
  display: flex;
  flex-direction: column;
  gap: 4px;
}
... for all `theme.gap` values, and the same with `hstack` and `flex-direction: row;`

This works great, but I'm facing an issue when using it with tailwind-merge, specifically, when I try to override the display property via something like .hidden:

twMerge('vstack-4 hidden') // 'vstack-4 hidden'

Ideally twMerge would break vstack-4 into: flex flex-col gap-4 and then I'd get back flex-col gap-4 hidden, but at the very least I want this to just return hidden, since none of the previous properties are relevant.

I tried to configure it via extendTailwindMerge, but could not really understand the configuration, even after reading the docs (#260 might help here).

Any help configuring tailwind merge here, in either configuration would be greatly appreciated.

P.S.
Here's the tailwind plugin I wrote to add these classes, in case it helps anyone:

tailwindShortcutStackPlugin.ts

```ts
import plugin from 'tailwindcss/plugin';

import { compact, objectEntries, omit } from '../_internal/utils';

export const tailwindShortcutStackPlugin = plugin(({ addUtilities, theme }) => {
  for (const [name, flexDirection] of objectEntries({
    hstack: 'row',
    vstack: 'column',
  } as const)) {
    addUtilities(
      Object.fromEntries(
        Object.entries<string | null>({
          // no prefix, no gap
          '': null,
          // we already have a gap-less utility 👆
          ...omit(theme<Record<number, string>>('spacing'), 0),
        }).map(([key, value]) => [
          compact([`.${name}`, key.replace('.', '\\.')]).join('-'),
          {
            display: 'flex',
            'flex-direction': flexDirection,
            ...(value && {
              gap: `${value}`,
            }),
          },
        ])
      )
    );
  }
});
```

[dcastil]

Note

Examples in this comment are using the tailwind-merge v1 API.

Hey @bengry! 👋 Thanks for your patience!

You need to tell tailwind-merge how conflicts with the vstack (and hstack) classes should be handled. Here a little tutorial:

First we want to use the default config and only add a bit more config to it, so we'll use extendTailwindMerge like this:

import { extendTailwindMerge } from 'tailwind-merge'

// We'll use this function for merging instead of the one exported from the tailwind-merge package
const twMerge = extendTailwindMerge({ /* our config here */ })

Then we want to resolve conflicts between the classes like vstack and vstack-4. For this we create a new class group. tailwind-merge will automatically resolve conflicts between all classes within that group.

import { extendTailwindMerge, validators } from 'tailwind-merge'

const twMerge = extendTailwindMerge({
    classGroups: {
        vstack: [{ vstack: ['', validators.isNumber] }],
    },
})

Now we want to remove vstack classes when other classes modifying the display property are used. We check the default config and figure out the ID of the display class group. Now we can tell tailwind-merge to remove vstack classes when display classes are present afterwards.

import { extendTailwindMerge, validators } from 'tailwind-merge'

const twMerge = extendTailwindMerge({
    classGroups: {
        vstack: [{ vstack: ['', validators.isNumber] }],
    },
    conflictingClassGroups: {
        display: ['vstack'],
    },
})

We probably also want to remove preceding display classes when we add a vstack class, so we also configure the conflict into the other direction:

import { extendTailwindMerge, validators } from 'tailwind-merge'

const twMerge = extendTailwindMerge({
    classGroups: {
        vstack: [{ vstack: ['', validators.isNumber] }],
    },
    conflictingClassGroups: {
        display: ['vstack'],
        vstack: ['display'],
    },
})

Additionally, we also want to remove preceding flex-direction and gap classes. So we make sure those are removed as well when a vstack is present afterwards.

import { extendTailwindMerge, validators } from 'tailwind-merge'

const twMerge = extendTailwindMerge({
    classGroups: {
        vstack: [{ vstack: ['', validators.isNumber] }],
    },
    conflictingClassGroups: {
        display: ['vstack'],
        vstack: ['display', 'gap', 'gap-y', 'flex-direction'],
    },
})

And that's it. Now you get this behavior:

twMerge('vstack-3 hidden') === 'hidden'
twMerge('gap-2 flex-row vstack-3') === 'vstack-3'

If you want to know how the configuration works, here is the documentation for it: https://github.com/dcastil/tailwind-merge/blob/v1.14.0/docs/configuration.md#usage-with-custom-tailwind-config.

And here is an example on how to configure tailwind-merge: https://github.com/dcastil/tailwind-merge/blob/v1.14.0/docs/recipes.md#adding-custom-scale-from-tailwind-config-to-tailwind-merge-config.

---

By the way, I find configuring helper classes like this in tailwind-merge quite complicated and annoying, especially if they define multiple CSS properties. So I use a different technique to create helpers like this where I don't need to configure anything in tailwind-merge: I define them as global variables which consist of the regular Tailwind CSS classes which tailwind-merge can work with by default.

E.g. when I know that I only use 4 different vstack classes, I'd define them like this in my codebase:

const VSTACK_1 = 'flex flex-col gap-1'
const VSTACK_2 = 'flex flex-col gap-2'
const VSTACK_3 = 'flex flex-col gap-3'
const VSTACK_4 = 'flex flex-col gap-4'

and then when I want to apply a vstack somewhere, I just use the variable:

function MyComponent({ className }) {
    return <div className={twMerge(VSTACK_2, /* more classes */, className)}>{/* code */}</div>
}

When someone calls <MyComponent className="hidden" />, the flex className which was added by VSTACK_2 is removed by tailwind-merge how you would expect it.

[bengry]

Thanks, this is a great explanation.
I wish the documentation would be on the same level, and examples more realistic. But hopefully this discussion can at least serve as a helper for anyone facing similar issues.

[bengry]

By the way, I find configuring helper classes like this in tailwind-merge quite complicated and annoying, especially if they define multiple CSS properties. So I use a different technique to create helpers like this where I don't need to configure anything in tailwind-merge: I define them as global variables which consist of the regular Tailwind CSS classes which tailwind-merge can work with by default.

E.g. when I know that I only use 4 different vstack classes, I'd define them like this in my codebase:

const VSTACK_1 = 'flex flex-col gap-1'
const VSTACK_2 = 'flex flex-col gap-2'
const VSTACK_3 = 'flex flex-col gap-3'
const VSTACK_4 = 'flex flex-col gap-4'

and then when I want to apply a vstack somewhere, I just use the variable:

function MyComponent({ className }) {
    return <div className={twMerge(VSTACK_2, /* more classes */, className)}>{/* code */}</div>
}

When someone calls <MyComponent className="hidden" />, the flex className which was added by VSTACK_2 is removed by tailwind-merge how you would expect it.

This requires importing these constants everywhere, which kind of ruins the appeal of tailwind, in some way. I like the fact that I have everything on-hand without needing to import anything, and the JIC compiler does the rest to tree-shake the unused stuff and the linter to warn me of non-existent classes.

This does make me think that perhaps tailwind-merge, or some other utility, could implement something like UnoCSS's shortcuts / PandaCSS's Patterns. i.e.

declare function twExpand(...classes: ClassValue[]): string;

twExpand('vstack-1') === 'flex flex-col gap-1'

Not perfect, since it does mean you have to use twExpand to use vstack-{number}, but IMHO Tailwind makes it too hard to add classes while integrating with the rest of the ecosystem, so maybe this can alleviate some of that 🤷

[dcastil]

Ah, cool idea! I think this function wouldn't even need to be part of tailwind-merge, since there you'd need to configure it anyway. You could create it yourself:

function twExpand(value: string) {
    return MAPPING[value]
}

const MAPPING = {
    'vstack-1': 'flex flex-col gap-1',
    // …
}

[Creative-Lee]

is there any way like this? twMerge('vstack-1 hidden') === 'flex-direction: column; gap: 4px; display:hidden;'
not this? twMerge('vstack-3 hidden') === 'display: hidden'

When I use a custom utility class (vstack-n in the example) and a utility class (hidden in the example) for a tw-merge function, I want to overwrite only the conflicting individual properties if they conflict with individual properties within the custom utility class and leave the remaining individual properties intact (in the example, I want to overwrite only the display properties and leave the flex-direction, gap)

[dcastil]

Hey @Creative-Lee! 👋

Yes, it's possible with the approach I explained at the bottom of #323 (comment) if you are ok with storing those classes in variables. But not possible if you just want to use strings unfortunately since tailwind-merge will only ever remove classes but never add any new ones.

[…] I use a different technique to create helpers like this where I don't need to configure anything in tailwind-merge: I define them as global variables which consist of the regular Tailwind CSS classes which tailwind-merge can work with by default.

E.g. when I know that I only use 4 different vstack classes, I'd define them like this in my codebase:

const VSTACK_1 = 'flex flex-col gap-1'
const VSTACK_2 = 'flex flex-col gap-2'
const VSTACK_3 = 'flex flex-col gap-3'
const VSTACK_4 = 'flex flex-col gap-4'

and then when I want to apply a vstack somewhere, I just use the variable:

function MyComponent({ className }) {
    return <div className={twMerge(VSTACK_2, /* more classes */, className)}>{/* code */}</div>
}

When someone calls <MyComponent className="hidden" />, the flex className which was added by VSTACK_2 is removed by tailwind-merge how you would expect it.