Beyond Utilities

Sooner or later you need something Tailwind does not ship: a 372px width, a selector that targets the children, a utility your team uses everywhere, a component class for markup you cannot edit. Tailwind gives you a ladder of escape hatches, and the skill is to take the lightest one that works: an arbitrary value, then an arbitrary property or variant, then your own @utility or @variant, then a class in @layer components (with @apply), and only then a plain stylesheet. This chapter climbs the ladder, and it explains the cascade-layer rule that decides whether your own CSS beats Tailwind's or loses to it.

Arbitrary Values

Put a value in square brackets and Tailwind uses it as written. The class name is the utility plus the value; you saw this in chapters 2 and 3 with p-[13px] and bg-[#bada55]. From the compiled output:

I measured a w-[calc(100%-2rem)] box inside a 600px parent: 568px (600 − 32). The writing rules are small: no spaces inside the brackets (use _ where you need one), and the whole class name must still appear in your files as one piece, which is the chapter 1 rule again.

CSS Variables as Values

To use a CSS variable, write it in parentheses: w-(--w) is shorthand for w-[var(--w)] and adds the var() for you. This is the right answer to a value that changes at run time, because a class name cannot be built from a variable (chapter 1) but a variable can be set from anywhere, including an inline style:

The one trap is type ambiguity. Several utilities share a prefix: text- sets font size or colour, bg- sets colour, image or size. Given only a variable, Tailwind cannot tell which you mean, so it picks colour, and I compiled the proof:

So a variable holding a size needs the hint, text-(length:--sz); the official docs show the same two hints for text-.

Arbitrary Properties and Variants

If there is no utility at all for a CSS property, write the property itself in brackets: [mask-type:luminance] compiled to mask-type: luminance and the element's computed value was luminance. Variants work in front, so hover:[mask-type:alpha] is a hover rule. A good use is setting a variable that other classes read, differently at different sizes:

Arbitrary variants do the same for selectors and conditions: a bracketed variant is a selector in which & stands for the element itself. All of these were measured or compiled:

The official docs describe arbitrary properties as "really like inline styles, but again with the benefit that you can use modifiers". They are for the rare one-off. If you find yourself writing the same bracketed class in many places, it deserves a name, which is the next rung.

Your Own Utilities and Variants

@utility defines a class that behaves like a built-in one, including working with every variant. A static one is a name and some declarations (nested selectors are allowed):

A functional utility takes a value from the class name: the * in the name stands for it, and --value() says what values are allowed. This one accepts a theme variable, a bare integer, or a bracketed integer:

The documentation shows each form of --value() on its own; I combined them in one list and it compiled and behaved as above. It also shows variants on static utilities only, so I checked a functional one: md:tab-2 worked. For variants, @custom-variant (chapter 8) defines a new condition. Its companion @variant goes the other way: it lets your own CSS use a Tailwind variant. This rule compiled to the media queries shown in the comments, and I measured it:

Cascade Layers: Who Wins, Your CSS or Tailwind's

Tailwind puts its output into cascade layers (chapter 1): theme, base, components, utilities, in that order of strength. You can add your own CSS to base (element defaults, such as sizes for h1 and h2) or components (classes like .card), and anything in utilities you define with @utility lands in the utilities layer. The reason to use @layer components is exactly that its place in the order is below the utilities, so you can still adjust a component with a class. I measured three cases:

@apply and @reference

@apply pastes the declarations of existing utilities into your own rule, which lets you name a combination once and use it on markup you cannot give lots of classes to:

Variants work inside @apply, and an ! at the end of a utility name produced !important (@apply bg-red-500! compiled to background-color: var(--color-red-500) !important; this form is not in the documentation, I tested it). The docs' own example is the right use: styling markup produced by something else (.select2-dropdown { @apply rounded-b-lg shadow-md; }).

Use @apply sparingly. It copies the declarations every time you use it, it moves your styling to a second file where you have to hunt for it, and it brings back the naming problem that utility classes were meant to remove. If the repetition is in your own templates, make a component (a partial, a function, a Vue or React component) so the classes are written once. Reserve @apply for markup you do not control.

@reference is for CSS that lives in a different file from your Tailwind import: a Vue or Svelte <style> block or a CSS module. That file does not know Tailwind's theme, so @apply fails. I compiled the same rule three ways:

So in a component file write @reference "../app.css"; (the path to your main stylesheet, so your custom theme, utilities and variants are known) and never @import "tailwindcss" again.

CSS Functions and Variables in Your Own CSS

In ordinary CSS you can use the theme directly. Tailwind adds two functions, and the older theme() still works:

--alpha() is the CSS equivalent of the /50 opacity modifier, and --spacing(4) of p-4. theme() is the v3 way: it compiled in 4.3.3, but the documentation lists it as deprecated and recommends theme variables, so prefer var(--radius-lg).

When to Write Plain CSS

Mixing is normal and healthy: Tailwind does not ask you to give up CSS, only to reach for it last. The next chapters stay in the utility world; Tailwind CSS Intermediate/Advanced 3 returns to custom utilities, variants and plugins in more depth.

Hands-On Exercises