Custom text size not being overridden by standard text utilities

[ali-issa]

What version of Tailwind CSS are you using?

4.1.11

What build tool (or framework if it abstracts the build tool) are you using?

Vite 7.1.7

What version of Node.js are you using?

bun 1.2.22

What browser are you using?

Chrome

What operating system are you using?

macOS

Reproduction URL

https://github.com/ali-issa/tailwind-text-utilities-bug

Describe your issue

When creating a custom text size utility using CSS theme variables as documented in the Tailwind CSS v4 documentation, the custom size cannot be overridden by standard text utilities when using tailwind-merge with clsx.

Steps to reproduce:

1. Define a custom text size in CSS:

@theme {
  --text-tiny: 0.625rem;
}

2. Create a component that uses the custom text size:

function MyComponent({ className }: { className?: string }) {
  return (
    <div className={cn("text-tiny", className)}>
      Sample text content
    </div>
  );
}

3. Try to override the text size when using the component:

<MyComponent className="text-xl" />

Expected behavior:

The text-xl class should override the text-tiny class, resulting in the text being displayed at the xl size.

Actual behavior:

The custom text-tiny class takes precedence and the text remains at the tiny size (0.625rem), ignoring the text-xl override and all other text-* classes.

Additional context:

• tailwind-merge version: ^3.3.1
• clsx version: ^2.1.1

[wongjn]

This isn't a Tailwind problem. Rather, you haven't configured Tailwind Merge to handle your custom theme token. You'd need to extend Tailwind Merge's default configuration:

--- a/src/App.tsx
+++ b/src/App.tsx
@@ -1,8 +1,16 @@
 import { clsx } from "clsx";
-import { twMerge } from "tailwind-merge";
+import { extendTailwindMerge } from "tailwind-merge";
 
 import type { ClassValue } from "clsx";
 
+const twMerge = extendTailwindMerge({
+  extend: {
+    theme: {
+      text: ['tiny'],
+    },
+  },
+});
+
 function cn(...inputs: Array<ClassValue>) {
   return twMerge(clsx(inputs));
 }

Before	After

[ali-issa]

Thanks for the tip. If it's a configuration issue, why does it only happen with text sizes and not with any other attributes like color? Having --color-chocolate: #482a2b; and overriding text-chocolate with text-black works fine with no issues.

Is it and expected inconsistent behavior?

[wongjn]

Tailwind Merge assumes all text- class names it does not know are text-<color> names. Hence why you need to be explicit for font size values.

[ali-issa]

tailwindcss/packages/tailwindcss/src/utilities.ts

Line 5075 in 85575a4

// `color` property

Color resolution uses resolveThemeColor() which searches ['--text-color', '--color']. Custom colors like --color-chocolate match --color namespace, but standard colors ALSO match --color, so they compete on equal footing.

tailwindcss/packages/tailwindcss/src/utilities.ts

Line 5083 in 85575a4

// `font-size` property

Font-size resolution uses theme.resolveWith() with ['--text'] as the PRIMARY namespace. Custom sizes like --text-tiny match this and get resolved, BUT standard text sizes like text-xl likely ALSO try to resolve against --text namespace first before falling back to other mechanisms.

I don't have much time to dig deeper, but I'm assuming that the bug is that custom --text-* variables get priority over standard text utilities because they're resolved in the same --text namespace, but the resolution mechanism doesn't properly handle the override order.

Improving the implementation would make tailwind more consistent and intuitive.

[ali-issa]

I'm not saying Tailwind should magically make text-lg override text-sm in all component scenarios. I understand CSS cascade limitations. I'm saying custom utilities shouldn't have different override behavior than standard utilities due to arbitrary CSS sorting rules. Whether text-tiny comes before or after text-xl in the CSS shouldn't depend on how many properties it has or alphabetical ordering.

Maybe I'm not communicating the issue clearly, but I think it would be better for one of the core maintainers to look into this. The current sorting behavior makes custom utilities unpredictable in ways that standard utilities aren't.

Thanks for your time on this.

[rozsazoltan]

I agree with Wongjn's point of view; this is more of a developer error than an architectural issue. It's an unexpected case to use conflicting utilities at the same time - for example, text-lg text-xl is inconsistent. Due to the way native CSS works, the class declared later in the CSS file takes precedence.

The order of classes in the class attribute has never mattered. But what if, in the case of text-lg text-xl, I sometimes want text-lg to win and other times text-xl? This is a conflict, which is why the order of classes in the class attribute cannot be taken into account. So again, only one can be stronger than the other based on CSS order, but how could anyone possibly decide whether text-lg or text-xl is more important to you? There's no way.

This should be avoided, and the component should be able to determine exactly which utility you need - text-lg or text-xl (in your case, or text-tiny). The default textSize and the option to override it, as mentioned in Wongjn's last reply, seems like a good approach.

Although this is a Vue post, it raises a similar overriding issue as the one the asker mentioned:

• https://www.reddit.com/r/vuejs/comments/1ltocb5/why_doesnt_my_prop_classname_override_default

Because class specificity doesn't depend on their order. Each class has its own strength. The TailwindCSS utilities you're using all have the same specificity level, so whether you can override one with another is often just a matter of luck.

To reliably override classes from the outside, you can use a package like Tailwind Merge, which keeps the last-added utility in cases of duplicates (e.g., bg-gray-100 bg-blue-500) and discards the earlier ones.

And what the previous link doesn't cover is the special configuration where a single utility prefix has multiple meanings. In that case, the configuration also needs to be passed to tailwind-merge - if you want to use it to solve the issue - so that tailwind-merge knows that in the case of text-tiny, tiny is not a color (even though it could be), but a font size. It won't look up the meaning itself, but it will accept a configuration, as mentioned:

• Custom text size not being overridden by standard text utilities #18999 (comment)

[ali-issa]

You're also completely missing the point.

What You Think The Issue Is

"User doesn't understand that CSS cascade order matters, not HTML class order"

What The Issue Actually Is

"Tailwind's CSS generation has inconsistent sorting rules that make custom utilities unpredictable"

The Key Point Everyone Keeps Missing

/* This is NOT about text-lg vs text-xl conflicts */
/* This is about INCONSISTENT behavior between: */

/* Case 1: Your custom utility sometimes comes AFTER standard ones */
.text-xl { ... }
.text-tiny { ... }  /* Wins due to CSS order */

/* Case 2: Your custom utility sometimes comes BEFORE standard ones */  
.text-tiny { ... }  /* Loses due to CSS order */
.text-xl { ... }

/* The position changes based on arbitrary factors like property count! */

This isn't about text-lg vs text-xl. It's about custom vs standard utilities.

The Real Issue

Whether text-tiny appears before or after text-xl in the generated CSS depends on:

• How many CSS properties each generates
• Alphabetical ordering
• Whether you defined --line-height

This makes custom utilities behave unpredictably compared to standard ones. That's the architectural inconsistency.

Even tailwind-merge Struggles With This

Why do custom colors work out-of-the-box with tailwind-merge, but custom text sizes require manual configuration?

// Custom colors: Just work
<Component className="text-chocolate" />  // tw-merge handles this fine

// Custom text sizes: Require manual config 
<Component className="text-tiny" />  // tw-merge thinks this is a color!

Fix needed ONLY for text sizes:

+const twMerge = extendTailwindMerge({
+  extend: {
+    theme: {
+      text: ['tiny'],  // Have to tell tw-merge this isn't a color
+    },
+  },
+});

This happens because even third-party tools can't reliably determine what a text-* utility does due to Tailwind's inconsistent patterns. If the architecture was consistent, tailwind-merge wouldn't need special configuration for custom text sizes.

[rozsazoltan]

You're also completely missing the point.

I understand your frustration. Thank you for framing your question. I think we're talking about the same thing, it's just that I offer explanations, while you want there to be a clear distinction - which is something I never wanted.

Well, it would clearly know what each utility does if the prefix were different: text-color-blue-500, text-size-lg - but why would we type all those extra characters? I don't see the problem. It's completely fine that this needs to be configured; in return, the class names will be shorter.

This problem also occurs, for example, when adding a variable:

<div class="text-(--custom)" style="--custom: 20px;">

But TailwindCSS does provide some extra configuration for classification:

<div class="text-(length:--custom)" style="--custom: 20px;">

So, as I concluded in my previous line of thought... I can live with the fact that text-* can mean several things, in exchange for not having to type extra characters for clarification.

You can observe the same with border and ring as well, where, to save characters, colors, sizes, and even types share the same utility-prefix.

Since it's fairly rare for me to add a new color, size, or type, I think it's reasonable to list these names for the external plugin as well to clarify my intention - this means +1 duplication per custom value. Whereas a naming scheme like border-size-*, border-color-*, border-type-* - which would be consistent, yeah - would require many, many more extra characters. I think I'd rather just make the names explicit and be done with it, instead of typing overly long class names.

[ali-issa]

I'm glad you understand the issue now. The problem isn't just about naming, it's that the CSS generation order for custom utilities is unpredictable based on arbitrary factors like property count and alphabetical sorting.

Even if we keep text-* for both colors and sizes, custom utilities should at least have consistent placement relative to standard utilities in the generated CSS. The current behavior where text-tiny can appear before OR after text-xl depending on whether you defined --line-height is objectively problematic, regardless of naming preferences.

But I understand if the team prioritizes brevity over predictability.

[rozsazoltan]

I know it's not a solution, but I'll leave it here anyway: do you really need to allow any className to be passed from the parent into the component? With an enum-like approach, you could pre-declare the component's styles and thus avoid class name collisions. I know it doesn't solve the problem - it just sweeps it under the rug - but it seems more consistent to predefine the component's appearance within the component itself. Something like this:

const styles = {
  blue: 'text-blue-500 text-lg',
  red: 'text-red-500 text-xl',
}

function MyComponent({ children, style = 'blue' }) {
  return <p class={styles[style]}>{children}</p>
}

<MyComponent>I am blue</MyComponent>
<MyComponent style="red">I am red</MyComponent>