twMerge creating conflict between custom size/width and color classes

Question

I have defined custom classes in TailwindCSS v4

"border-x-xs border-border"

where as border-x-xs is for border width and border-border is for color.

When I use cn() function twMerge is creating conflict betweeen both and is keeping only one class that the one used at last that is if I use.

"border-x-xs border-border" but there's no conflict if I write "border-border border-x-xs"

How do I know it's a conflict? because the border-x-xs is not there in the browser console.

borderColor: ["foreground", "foreground-muted", "border"],
borderWidth: ["x-xs","x-sm","x-md","x-lg","x-xl","x-2xl","x-3xl","x-4xl","x-5xl",],
borderRadius: ["x-sm", "x-md", "x-lg"],

I also added these in theme in extendTailwindMerge but it didn't work? What could be the issue here? Remember I'm using TailwindCSS v4.

Edit:

/* SPACING */
--spacing-x-xs: var(--xs);
--spacing-x-sm: var(--sm);
--spacing-x-md: var(--md);
--spacing-x-lg: var(--lg);
--spacing-x-xl: var(--xl);
--spacing-x-2xl: var(--2xl);
--spacing-x-3xl: var(--3xl);
--spacing-x-4xl: var(--4xl);
--spacing-x-5xl: var(--5xl);
/* BORDER WIDTH */
--border-width-x-xs: var(--xs); /* 2px */

/* BORDER COLOR */
--border-color-accent-primary: hsl(var(--accent-primary)); /* 2px */

This is my tailwind configuration for spacing and border (where x- is to show that it's a custom value which i just realized could be falsely interpreted as values for x axis)

I've never understood why it's a good idea to name colors based on where they're used, just to make sure they're pointless to reuse elsewhere. — rozsazoltan
– rozsazoltan, Commented Jun 15 at 8:58
Related: tailwindlabs/tailwindcss discussion #19020 - Which TailwindCSS v4 namespace matches a given TailwindCSS v3's theme keys? — rozsazoltan
– rozsazoltan, Commented Sep 27 at 9:09

rozsazoltan · Accepted Answer · 2025-06-15 09:55:32Z

You didn't share your v4 configuration, so your border-x-xs and border-border declarations aren't really clear. Starting with TailwindCSS v4, the JavaScript-based configuration has been removed by default, and instead, you configure these kinds of custom values using namespaces in a CSS-first configuration.

What's breaking changes from TailwindCSS v4? - StackOverflow
New CSS-first configuration option in v4 - StackOverflow

It's important to note that for utilities like border-width, width, height, margin, padding, etc., the values are controlled by a central --spacing variable. As a result, you can't define new values for these by default. So valid widths would be something like border-1 or border-2, but border-xs is not valid.

How to use custom color themes in TailwindCSS v4 - StackOverflow

You can customize these settings using the @theme directive, but as mentioned, since widths, heights, and other sizing values are governed by the central --spacing, it's not possible (and would be inconsistent) to define special border-width values. This somewhat explains why tailwind-merge might not properly interpret your input. Two different results in two similar-looking cases could be due to internal logic differences, so I'd suggest opening an issue in the repository.

@theme directive - TailwindCSS v4 Docs
Theme variable namespaces - TailwindCSS v4 Docs

The extendTailwindMerge function in tailwind-merge also adapts to the namespaces used in the CSS-first configuration. As a result, extend.theme.borderColor, extend.theme.borderWidth, and extend.theme.borderRadius are no longer available.

In v4, the new namespace for borderRadius is rounded-*, which you can configure using extend.theme.rounded when using extendTailwindMerge.

Tailwind Merge Theme Configuration Keys - Tailwind Merge Docs

As I mentioned earlier, according to the v4 documentation, it's not possible to customize border-color or border-width directly, so naturally, this isn't supported in twMerge either.

Example for a custom color name

<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
<style type="text/tailwindcss">
@theme {
  --color-border: #da373d; /* not reusable, I don't recommend border as a name */
}
</style>

<div class="w-32 h-32 border-2 border-border text-border">Hello World</div>

Example for a custom color name usable only for borders

<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
<style type="text/tailwindcss">
@theme {
  /* undocumented, expected to be deprecated in the future */
  --border-color-border: #da373d; /* not reusable, I don't recommend border as a name */
}
</style>

<div class="w-32 h-32 border-2 border-border text-border">Hello World</div>

Example of introducing a custom border-width (using a custom utility)

<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
<style type="text/tailwindcss">
@theme {
  /* undocumented, expected to be deprecated in the future */
  --border-color-border: #da373d; /* not reusable, I don't recommend border as a name */
  
  /* new custom namespace by --value(--border-width-*) */
  --border-width-xs: 10px;
  --border-width-sm: 20px;
  --border-width-md: 40px;
}

/* new custom utility for border-width */
@utility border-* {
  border-width: --value(--border-width-*);
}

/* new custom utility for border-y-width */
@utility border-y-* {
  border-top-width: --value(--border-width-*);
  border-bottom-width: --value(--border-width-*);
}

/* new custom utility for border-x-width */
@utility border-x-* {
  border-left-width: --value(--border-width-*);
  border-right-width: --value(--border-width-*);
}

/* new custom utility for border-t-width */
@utility border-t-* {
  border-top-width: --value(--border-width-*);
}

/* new custom utility for border-b-width */
@utility border-b-* {
  border-bottom-width: --value(--border-width-*);
}

/* new custom utility for border-l-width */
@utility border-l-* {
  border-left-width: --value(--border-width-*);
}

/* new custom utility for border-r-width */
@utility border-r-* {
  border-right-width: --value(--border-width-*);
}
</style>

<div class="w-32 h-32 border-x-xs border-y-md border-border text-border">Hello World</div>
<div class="w-32 h-32 border-x-sm border-y-sm border-red-400 text-border">Hello World</div>
<div class="w-32 h-32 border-x-md border-y-xs border-red-200 text-border">Hello World</div>

In this case, it is the responsibility of Tailwind Merge to ensure the correct order, but your TailwindCSS v4 configuration is at least perfect for the desired result.

Collectives™ on Stack Overflow

twMerge creating conflict between custom size/width and color classes

1 Answer 1

Example for a custom color name

Example for a custom color name usable only for borders

Example of introducing a custom border-width (using a custom utility)

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Example for a custom color name

Example for a custom color name usable only for borders

Example of introducing a custom border-width (using a custom utility)

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related