Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 37 ยท Utility Basics

Arbitrary Values and !important

Break out of the Tailwind scale when you must: square-bracket values, CSS variable shorthand, arbitrary properties and variants, and the important modifier.

The design scale covers most needs, but real projects always have exceptions: a brand color from a style guide, a hero that is exactly 37.5rem wide, a CSS property Tailwind has no utility for. Instead of leaving the framework, you use arbitrary values. They let you write any CSS value inside a utility, and they generate a real class on demand.

Square-bracket values

Put the value in [...] after the utility name:

HTML
<div class="w-[37.5rem] bg-[#316ff6] top-[117px] text-[22px]"></div>

Everything that accepts a value accepts brackets: sizes, colors, spacing, grid templates, shadows, z-index. Some rules:

  • No spaces. Use an underscore for a space: grid-cols-[1fr_2fr] becomes grid-template-columns: 1fr 2fr. To keep a literal underscore, escape it: \_.
  • calc() works. h-[calc(100dvh-4rem)] needs no spaces around the minus because Tailwind adds them for you inside calc.
  • Quotes for strings. Content utilities use quoted text: before:content-['โ˜…'].
Arbitrary sizes, colors and grids

Hinting the type

Sometimes Tailwind cannot tell what kind of value you mean. text-[22px] is a font size, but text-[#336] is a color. For ambiguous cases, such as a variable, add a type hint before the value:

HTML
<p class="text-[length:var(--my-size)]">   <!-- font-size -->
<p class="text-[color:var(--my-color)]">   <!-- color -->

CSS variables: the parenthesis shorthand

Variables are common in arbitrary values, so v4 gives them a shorter syntax with parentheses. Wrapping the variable in (...) is the same as [var(--x)]:

HTML
<div class="bg-(--brand) w-(--sidebar-width) p-(--gap)"></div>

(In v3 this was bg-[--brand]; v4 changed it to bg-(--brand).) Variables can come from your own :root, from a parent element with an inline style, or from the theme. The inline-style approach is the best way to pass a dynamic value, such as a color from a database, into a utility without needing the full class name in advance:

CSS variables in utilities

The two boxes share the same classes but differ in size and color because the variables differ. This is the reliable pattern for dynamic styling.

Arbitrary properties

If Tailwind lacks a utility for a CSS property, wrap the whole declaration in brackets:

HTML
<div class="[mask-type:luminance] [--ring-width:3px] [text-wrap:balance]"></div>

This writes mask-type: luminance (and so on). Combine with variants: hover:[mask-type:alpha], lg:[--gap:2rem]. It is perfect for brand-new CSS features that Tailwind has not added yet.

Arbitrary variants

Variants can be arbitrary too. Write a selector in brackets, with & standing for the element itself:

HTML
<ul class="[&>li]:py-2 [&_a]:underline [&:nth-child(3)]:font-bold"> ... </ul>
  • [&>li]:py-2 applies py-2 to direct li children.
  • [&_a]:underline targets any descendant a (underscore = space in selectors).
  • [@media(min-width:900px)]:flex writes a custom media query.
Arbitrary properties and variants

Use this for rarely needed structure styling, for instance when you cannot add classes to nested HTML (such as rendered Markdown). If you write many of them for one pattern, extract a component or a custom variant (chapter 7).

The important modifier

Normally utilities beat your base styles thanks to layers, so you rarely need !important. When you must override a stubborn rule, a third-party widget or an inline style, add ! at the end of the utility in v4:

HTML
<div class="bg-red-500 text-white p-4!"></div>

That generates padding: 1rem !important. You can use it with variants: hover:bg-sky-700!. The old v3 form with the exclamation mark at the start (!p-4) still works, but end-of-name is the v4 documentation style.

Treat ! as a last resort. If you find yourself adding it everywhere, a specificity or ordering problem is hiding underneath. Check class conflicts first (two utilities setting the same property on one element).

To make everything important, for example when embedding Tailwind inside a legacy page, use @import "tailwindcss" important; in your CSS. This is rarely appropriate.

Arbitrary values vs the theme

Situation Better choice
One-off value used once Arbitrary value w-[37.5rem]
Value used in many places (brand color, a spacing step) Add it to @theme (chapter 6)
A value that changes at runtime A CSS variable size-(--size)
A property with no utility Arbitrary property [x:y]

If you see the same [#316ff6] ten times, it belongs in the theme.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you write the CSS value "1fr 2fr" in an arbitrary grid template class?

    Spaces are not allowed in class names, so Tailwind uses underscores, which become spaces in the generated CSS.
  2. 2. In v4, which syntax uses a CSS variable as a background color?

    v4 introduced the parenthesis shorthand for variables; the older bracket form without var() no longer applies.
  3. 3. What does p-4! generate?

    A trailing exclamation mark appends !important to the declaration.
  4. 4. What is [&>li]:py-2 an example of?

    Square brackets with & define a custom selector variant, here applying py-2 to direct li children.

Summary

  • Brackets put any CSS value in a utility: w-[37.5rem]; underscores replace spaces.
  • Use (--var) shorthand for CSS variables and type hints (text-[length:...]) when ambiguous.
  • Arbitrary properties ([mask-type:luminance]) and arbitrary variants ([&>li]:py-2) cover anything else.
  • ! at the end makes a utility important; use it rarely.
  • Repeated arbitrary values belong in @theme.

Next: Display, Position and Overflow