Not clear how to add z-index to @theme

[DennisWoering-xs2]

I think the documentation for z-index could be improved, I was trying to add a z-index to my theme. But I couldn't find how. I tried doing

@theme {
  --z-toast: 200;
}

But this didn't work, as you have to do --z-index-toast: 200, which is pretty obvious in hindsight, but I didn't realize it. Is it an idea to make a small section for z-index on how to add values to the theme?

[rozsazoltan]

In @theme, you can only assign values to the namespaces explicitly listed in the documentation. These namespaces are hardcoded to determine exactly what they will generate later. TailwindCSS cannot process undeclared namespaces - they'll simply be treated as plain variables.

• Theme variable namespaces - TailwindCSS v4 Docs

The z-index cannot be extended with such values in @theme because it only accepts numeric values. Starting from v4, it works entirely dynamically - for example: z-1, z-20, z-200, etc.

• Layout: z-index - TailwindCSS v4 Docs

If you want to create a custom utility with a specific name, use the @utility directive like this:

@utility z-toast {
  z-index: 200;
}

• @utility directive - TailwindCSS v4 Docs

You can now use your z-toast utility, which is essentially equivalent to z-200.

Some extra example for utilities using:

• TailwindCSS v4 and new @utility CSS-first directive - StackOverflow
• How to stop TailwindCSS animation after a set time - StackOverflow
• TailwindCSS fallback screen height - StackOverflow
• Special utilities for h-screen and w-screen - StackOverflow