Tailwind v4 Syntax Cheatsheet

Tailwind v4 has new syntax for arbitrary values, variants, properties, and more. Here's the cheatsheet that I would have wanted when I first started using it.

Terms Primer

Property: Indicates an aspect of the appearance or layout of an element, such as margin or color. Are set to a value.
- Custom Property (or CSS Variables): A property that is user-defined and is prefixed with --, such as --my-brand-color. Also are set to a value.
Value: Defines the specific setting for a property, such as 1rem or red.
Utility Class: (Tailwind-specific) are HTML element classes that set a property to a value. For example, bg-red-500 is a utility class that sets the background-color property to the value red-500. This is the meat of Tailwind.
Variant: (Tailwind-specific) Conditionally apply a utility class. For example, hover:bg-red-500 applies the bg-red-500 utility class when the element is hovered.
Function: (Tailwind-specific) return a value based on parameters of Tailwind's design system. For example, spacing(4) returns the value of the spacing scale for 4, as seen in something like m-4.

Arbitrary Properties

For utilities that tailwind does not support:

<!-- tailwind has no utility for mask-type -->
<div class="[mask-type:luminance] hover:[mask-type:alpha]">
  <!-- ... -->
</div>

Arbitrary Values

When tailwind does support the property, but its tokens do not support the value:

<div class="bg-[#bada55] text-[22px] before:content-['Festivus']">
  <!-- ... -->
</div>

Arbitrary Values that are Custom Properties (or CSS Variables)

If the value is a custom property, you can save yourself from typing fill-[var(--my-brand-color)] with this shorthand:

<div class="fill-(--my-brand-color) ...">
  <!-- ... -->
</div>

Sometimes, because tailwind overloads utility names for different properties, there can be ambiguity. For example, the text- utility can be for either font-size or color.

<div class="text-(--my-var)">...</div>
<!-- uhh, is this a color or a font-size? tailwind needs to know. -->

So, you may have to hint to tailwind which property you mean:

<!-- Will generate a font-size utility -->
<div class="text-(length:--my-var)">...</div>
<!-- Will generate a color utility -->
<div class="text-(color:--my-var)">...</div>

Setting Custom Properties (or CSS Variables) on the Fly

Instead of putting a CSS variable in a stylesheet, you can declare it in HTML/components:

<div class="[--gutter-width:1rem] lg:[--gutter-width:2rem] w-(--gutter-width)">
  <!-- ... -->
</div>

Arbitrary Variants

Arbitrary variants let you write custom selector variants directly in your HTML.

They are just format strings that represent the selector, wrapped in square brackets.

<ul role="list">
  {#each items as item}
  <li class="[&.is-dragging]:cursor-grabbing">{item}</li>
  {/each}
</ul>

Functions

You can use tailwind's design system for spacing and alpha to keep the numbers consistent.

<div class="py-[calc(--spacing(4)-1px)] px-4">
  <!-- ... -->
</div>

Directives

Directives are custom Tailwind-specific at-rules you can use in your CSS that offer special functionality for Tailwind CSS projects.

Custom Utilities

This is useful for turning a set of tailwind classes into a reusable utility class.

@utility skeleton {
  @apply animate-pulse bg-muted text-muted-foreground/30;
}

Then, use the utility in your HTML:

<div class="skeleton">
  <!-- ... -->
</div>

Variants

(Generally, this is only useful when you define classes in CSS, something tailwind largely allows you to not do.)

Every utility class in Tailwind can be applied conditionally by adding a variant to the beginning of the class name that describes the condition you want to target. For example, hover:bg-blue-500 applies the bg-blue-500 utility when the element is hovered.

To create your own variants, you can use the @variant directive.

.my-element {
  background: white;
  @variant dark {
    background: black;
  }
}

Or nest:

.my-element {
  background: white;
  @variant dark {
    @variant hover {
      background: black;
    }
  }
}

Then, use the variant in your HTML:

<div class="my-element">
  <!-- ... -->
</div>

Custom Variants

If you have a set of variants that you commonly use, you can create a shorthand for them.

/* Equivalent to utility class `not-first:not-last:<whatever>` */
@custom-variant middle {
  &:not(&:first-child) {
    &:not(&:last-child) {
      @slot;
    }
  }
}

Then use the custom variant in your HTML:

<div class="middle:mx-4">
  <!-- ... -->
</div>

Note that you must use native CSS selectors in the @custom-variant directive. And, the @slot directive is a placeholder for the utility classes you want to apply to the element.

See tailwind's default variants section to see the CSS selectors they use here.

t-mart/cheatsheet.md