Additive utility properties

[emmnull]

Rationale

Atomic/generic classes are inherently constrained by the cascading nature of CSS when it comes to same-property composability across multiple declarations. For lack of a proper native additive syntax, tailwind navigates this limitation by relying on internally pre-defined custom properties lists to place-hold potentially "additive" values. One example would be filter utilities which include a common filter chain that translates into something like

filter: var(--tw-blur,) var(--tw-brightness,) var(--tw-contrast,) var(--tw-grayscale,) var(--tw-hue-rotate,) var(--tw-invert,) var(--tw-saturate,) var(--tw-sepia,) var(--tw-drop-shadow,);

Except, this remains a somewhat blackboxed solution that is currently not extendable through a proper API. Thus, when wanting to create custom filter utilities using either the @utility syntax or the legacy js plugin API, users need to either throw that system out completely or manually redeclare an extended version of the variable list. The former leads to losing any additive capabilities, the latter is tedious, error-prone, and lacks any convention to guarantee compatibility with other third party plugins.

Proposal

Add an plugin API or a custom CSS syntax that allows to conventionally stack values on composable properties across multiple utilities in a way that enables both default and custom utilities to co-extend each other.

Prefixed theme variables

One way to achieve this would be to detect and auto-extend listable properties based on theme variable names that target them. This approach moves away from explicitly defined lists and would instead derive a property's composition based on scannable theme variables.

@theme {
  @property --filter-foo {
    syntax: "<url>";
    inherits: false;
    initial-value: "";
  }
}

@utility foo {
  --filter-foo: url(...);
}

would yield:

.foo {
  filter: var(--tw-blur,) var(--tw-brightness,) /*...*/ var(--filter-foo,);
}

Major caveat is this is still somewhat obscure and works only for non-inheritable variables.

Custom additive syntax

Here a custom syntax would be used to flag which values should be composed together.

/* Using a custom function syntax */
@utility bar {
  filter: --append(url(...));
}

/* Using an "add" annotation as currently under discussion */
@utility baz {
  filter: url(...) !add;
}

[Om-singh-ui]

I ran into the same issue while setting up Tailwind with Nuxt.

The TypeScript error happens because the plugin returned by @tailwindcss/vite doesn't perfectly match the PluginOption type Nuxt expects. A simple workaround is to cast it so TypeScript stops complaining:

import tailwindcss from "@tailwindcss/vite"

export default defineNuxtConfig({
  compatibilityDate: "2025-07-15",
  devtools: { enabled: true },
  vite: {
    plugins: [
      tailwindcss() as any,
    ],
  },
})

I also hit the 404 error mentioned in step 5 of the guide. The path in the docs uses ./app/..., but Nuxt usually resolves project assets through the ~ alias. Changing it to this fixed the issue for me:

css: ['~/assets/css/main.css']

After updating the path, the stylesheet loaded correctly and the 404 error disappeared.

Might be worth updating the docs to reflect this

[emmnull]

This is completely unrelated to the discussion at hand here...

[Om-singh-ui]

You're right my mistake. I mixed this up with a Nuxt + Tailwind setup issue.
Thanks for pointing it out.

[Om-singh-ui]

@emmnull

One possible approach could be exposing the filter chain so plugins can append to it instead of redefining the whole property.
Right now custom utilities have to recreate the full chain:

CSS

filter: var(--tw-blur,) var(--tw-brightness,) var(--tw-contrast,) var(--tw-grayscale,) var(--tw-hue-rotate,) var(--tw-invert,) var(--tw-saturate,) var(--tw-sepia,) var(--tw-drop-shadow,);

If there were a shared extension point (for example something like --tw-custom-filter at the end of the chain), plugins could simply set that variable and stay compatible with the default utilities without redeclaring everything.

That would keep the composable model while making custom filter utilities easier to extend.

[emmnull]

Yeah, I was thinking about something similar, but unless the extension point somehow supports multiplicity, this would not prevent different plugins from conflicting with each other.

For example, let's say we have two plugins or packaged utilities:

@utility filter-a {
  --tw-custom-filter: url(...);
}

@utility filter-b {
  --tw-custom-filter: url(...);
}

Then it would not be compatible with using both of them simultaneously (unless both packages agree on some intermediate convention to combine into a single extension point, which just nudges the problem)

@import 'tailwindcss-filter-a';
@import 'tailwindcss-filter-b';

<div class="filter-a filter-b">...<div>

This is fundamentally similar to the limitations faced with animation/transition plugins which generally define their own internal property lists. I think it boils down to needing an API let utilities co-extend lists defined by both default utilities and custom utilities / plugins. This likely will need to rely on compile-time heuristics beyond css variables chaining. Maybe something along the lines of:

/* signaling to tailwind based on theme property naming */
@theme {
  --filter-foo: ;
}
@utility filter-foo {
  --filter-foo: url(...);
}

/* or using the @property multiplier (+ or #) syntax on target properties. */
@utility filter-bar {
  filter#:  url(...);
}

/* or using some custom function */
@utility filter-baz {
  filter: --append(url(...));
}

[Om-singh-ui]

That makes sense the conflict between multiple plugins targeting the same extension point is the tricky part.

Maybe instead of a single variable like --tw-custom-filter, Tailwind could internally maintain something like a staged list (similar to how the core filter utilities already compose multiple variables) and allow plugins to register additional stages.

So each plugin would contribute its own variable, for example:

CSS

--tw-filter-plugin-a
--tw-filter-plugin-b

and Tailwind would merge them into the final filter chain during generation. That way plugins wouldn’t need to coordinate conventions between themselves and the composability model would stay intact.

[emmnull]

I did a bit of research to see if there were discussions around a syntax for appending to property values and stumbled on w3c/csswg-drafts#1594 where a !add annotation is proposed and a few use cases are discussed. While some points can be made against for such a syntax in native css, I believe it remains within a relevant feature scope for tailwind.