Utilities and Plugins

Sooner or later you want a class Tailwind does not have: content-auto, a stack-3 that follows your spacing scale, a hocus: variant for hover-or-keyboard-focus, a prose class for rendered Markdown. Tailwind v4 gives you five ways to add one, and picking the wrong one is the usual mistake. This chapter builds each one, shows exactly what it generates, and ends with a rule for choosing. It assumes Tailwind CSS Fundamentals 10 (arbitrary values, @layer and @apply) and Tailwind CSS Intermediate/Advanced 1 (how the layers work).

Which Mechanism Do I Need?

Start from what you are trying to add, not from the feature name:

Static Utilities: @utility

The simplest case is a name and some declarations. It lands in the utilities layer, so every variant works on it for free. I wrote two and used them with hover: and lg::

Two things to know. First, nesting (&::-webkit-scrollbar) is how one utility writes more than one rule. Second, a name that already exists is merged, not replaced. I defined @utility underline { text-decoration-line: line-through; } and the output was a single .underline rule containing both declarations, underline first and line-through second, so mine won. That is occasionally useful and usually an accident. A custom utility can also be used in your own CSS: .card { @apply glow-brand p-4; } compiled to a plain rule with both utilities' declarations.

Functional Utilities: --value() and --modifier()

End a name with -* and the utility takes a value. The --value() function says what values are legal, and a class whose value does not match is simply not generated:

Notice that several --value() declarations in one rule are tried in turn and the ones that fail are dropped; that is how stack-3 and stack-[10px] both work from one utility. Notice also that the negative version, -nudge-2, needed its own @utility -nudge-*: a negative is never derived for you.

Custom Variants: @custom-variant

A variant is a condition wrapped around a utility. The short form takes a selector in brackets; the block form wraps @slot (where the utility's declarations go) in whatever you need:

What the output shows:

• :where() keeps specificity at zero. The theme-midnight selector is wrapped in it, so the variant never makes a utility harder to override than the same utility without the variant.
• Conditions nest. desktop-hover needs a wide screen and a hover-capable device, and two nested @media blocks say exactly that.
• You can build a variant out of existing ones. dark-hover uses @variant dark and @variant hover inside @custom-variant, and the output contains both conditions. (The course outline called this "compound @variant, v4.3". The documentation page does not use that term, so I tested the behaviour rather than the name; it works in 4.3.3 and I did not check which release first allowed it.)
• Everything combines. md:theme-midnight:p-2 and theme-midnight:hover:text-white work, and group-hocus: appeared with no extra work.

Tailwind's Variants in Your Own CSS: @variant

Use @variant inside a rule you write yourself (for example a legacy class) to get Tailwind's variants without repeating the media queries:

Stacking (hover:focus) nests the conditions and a comma list repeats the declarations for each variant. One caution from chapter 1: this .btn rule is outside every layer (the output shows it after the @layer blocks), so it beats utilities such as p-8 on the same element. Wrap it in @layer components if you want utilities to win.

Official Plugins: Typography and Forms

A plugin is added with one line. Both official plugins declare Tailwind 4 in their peerDependencies and both worked in my build. Each adds rules, so I measured the cost and the effect. The baseline stylesheet (one page, no plugin) was 4,614 bytes:

Points from those numbers. Typography turned unstyled HTML (an h2, a paragraph, a link, a list) into styled content through one class; the link became underlined with weight 500. After I renamed the class to wysiwyg, the markup still said prose prose-lg and neither did anything: the heading was the base 24px, not the 30px of prose-lg. The class option replaces the name; it does not add an alias. Forms by default restyles every bare input in the project, which is what you want for a quick reset and not what you want if other CSS styles those inputs; strategy: class leaves plain inputs alone and only styles those with the class. The sizes depend on which of the plugin's classes your pages use, so treat them as one measurement, not a constant.

Writing a Plugin

The JavaScript plugin API is still the way to ship something other people install, or to generate many rules from data. A plugin file exports a function; plugin.withOptions() lets the CSS pass it options. Here is a small one that uses most of the helpers:

The markup and what came out:

Three lessons from running it, each of which cost me a wrong first version:

• Name collisions are silent. My first plugin utility was called text-shadow-md. Tailwind already has text-shadow-* utilities, and the output was one rule with both declarations, the built-in's three-layer shadow and then mine, so mine won only because it came last. I renamed it glow-text-*. Check a name against the built-in list before you ship it.
• theme() returns the literal value, not a var(). accent-ring-brand compiled to oklch(0.55 0.2 260), whereas the @utility glow-* from earlier compiled to var(--color-brand). A plugin utility therefore does not follow a variable that you re-define per theme (chapter 2). Use @utility with --value() when theming matters.
• addComponents did not use the components layer in this version: .pill was emitted with the utilities. It was still overridden by p-8 and px-8 (padding read from the browser: 12px/4px alone, 32px left with px-8, 32px all round with p-8), because it was written before them, but do not depend on a layer guarantee. For a real component class, write @layer components { … } in CSS.

Rule of thumb: reach for @utility first. Move to a JavaScript plugin only when you need options, loops over data, or distribution through npm.

Legacy Configs: @config

A project moving from v3 can keep its tailwind.config.js with @config "./tailwind.config.js";. I wrote a config that used six common v3 options and checked which still took effect:

So a bridge config will keep most of a v3 theme working, but safelist and corePlugins fail silently, the same way as every other mistake in this course: no error, no rule. Chapter 8 walks through moving a v3 project fully into CSS.

Hands-On Exercises