Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 37 ยท Components and Reuse

Custom Utilities and Variants

Create your own Tailwind CSS v4 utilities with @utility, functional utilities using --value(), custom variants with @custom-variant and @slot, and plugins.

Tailwind's vocabulary is large, but your project will have needs it cannot guess: a scrollbar-hidden helper, a tab-* family, a hocus: variant that means "hover or keyboard focus". Version 4 lets you add these in CSS, with two directives: @utility and @custom-variant. A custom utility behaves like a built-in one. It works with every variant (md:, hover:, dark:), it can be used in @apply, and it appears in the output only when you use it.

@utility: a simple custom utility

A simple utility is a name and a block of declarations.

CSS
@utility content-auto {
  content-visibility: auto;
}

@utility scrollbar-hidden {
  scrollbar-width: none;
  &::-webkit-scrollbar { display: none; }
}

CSS nesting with & is allowed inside. Once defined, content-auto and scrollbar-hidden work anywhere, including md:scrollbar-hidden and hover:content-auto, because Tailwind attaches variants to the utility for you. That is the big difference from a .class in @layer components, which cannot be used with variants unless you write the variants by hand.

A custom utility with variants

Functional utilities with --value()

A utility whose name ends in -* takes a value after the dash, like p-4 or bg-brand. The function --value() receives that value and checks it against several possible sources, trying them in order.

CSS
@theme {
  --tab-size-github: 8;
}

@utility tab-* {
  tab-size: --value(--tab-size-*, integer, [integer]);
}

This single definition accepts three kinds of values:

Class Matched by Result
tab-github the theme namespace --tab-size-* tab-size: 8
tab-4 the bare type integer tab-size: 4
tab-[12] an arbitrary value with type [integer] tab-size: 12

Other useful types: number, percentage, ratio, color, length, string. For spacing-style numbers, wrap the value with --spacing():

CSS
@utility pad-* {
  padding: --spacing(--value(integer));   /* pad-5 is 5 * var(--spacing) */
}
Functional utilities: shadow color and spacing

The first utility reuses your theme colors (text-glow-brand) and also accepts any color in brackets. That is the pattern for all "color-shaped" utilities: look in --color-* first, then allow [color].

Utility names must be a single word of letters, digits and dashes, and cannot be a name Tailwind already uses for something with different meaning. If a class does nothing, check for a typo in the name before the body.

@custom-variant: your own prefixes

A custom variant is a selector or at-rule you can put in front of any utility. Two syntaxes cover almost everything.

Shorthand: a selector (or a list) with & standing for the element.

CSS
@custom-variant hocus (&:hover, &:focus-visible);
@custom-variant theme-midnight (&:where([data-theme=midnight] *));
@custom-variant is-loading (&:where([aria-busy=true], [aria-busy=true] *));

Long form: a block with @slot, where the utility's styles go. Use it for media queries and nesting.

CSS
@custom-variant pointer-hover {
  @media (hover: hover) {
    &:hover { @slot; }
  }
}

pointer-hover:bg-blue-500 now applies a hover background only on devices that really hover, which avoids the "sticky hover" problem on touch screens.

hocus and a data-attribute variant

Variants inside CSS: @variant

When you write your own CSS and need a variant's condition, use @variant instead of copying the media query. It keeps your code in sync with the theme.

CSS
.sidebar {
  width: 100%;
  @variant md { width: 16rem; }
  @variant dark { background: var(--color-slate-900); }
}

Here md expands to the right media query, using whatever breakpoint the theme defines.

Plugins and external files

Two more directives round out the toolbox:

  • @plugin "@tailwindcss/typography"; loads an official or third-party plugin. The typography plugin gives you the prose classes for styling rendered Markdown, and the forms plugin gives you consistent form defaults. Plugins are npm packages, so this works in a build setup, not in the browser preview.
  • @source "../vendor/**/*.blade.php"; tells Tailwind to scan extra files for class names. @source inline("underline underline-offset-4") safelists classes that are never written as literal strings in your source.

Both appear in Build Tools and Upgrading in a complete setup.

Choosing the right tool

You want Use
A named bundle you can use with variants @utility
A named, parameterized helper (tab-4) @utility name-* with --value()
A reusable condition (hocus:) @custom-variant
A class for HTML you cannot edit @layer components with @apply
A one-off value an arbitrary value like w-[37rem]

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main advantage of @utility over a .class in @layer components?

    Custom utilities are registered like built-ins, so any variant can be put in front of them.
  2. 2. What does tab-* with --value(--tab-size-*, integer, [integer]) accept?

    --value tries each listed source in order.
  3. 3. Which defines a variant hocus for hover or keyboard focus?

    The shorthand form takes a selector list where & stands for the element.
  4. 4. What is @slot used for?

    Inside a long-form @custom-variant, @slot is replaced by the styles of the utility the variant is applied to.

Summary

  • @utility name { ... } defines a simple utility that works with every variant.
  • @utility name-* { ... --value(...) } defines a utility with a value taken from the theme, a bare type or a bracketed arbitrary value.
  • @custom-variant creates prefixes from selectors (shorthand) or from media queries with @slot (long form); @variant uses a variant inside your own CSS.
  • @plugin loads plugins and @source adds files to scan.

Next: Arbitrary Values and Resolving Conflicts