Creating Custom Utilities

Purpose

The @utility directive creates custom utility classes with full variant support (hover, focus, responsive, etc.). This is the proper way to extend Tailwind v4 with custom utilities.

Static Utilities

Define utilities with fixed values:

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

@utility content-hidden {
  content-visibility: hidden;
}

@utility text-balance {
  text-wrap: balance;
}

@utility text-pretty {
  text-wrap: pretty;
}

@utility bg-glass {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(10px);
  border: 1px solid rgba(255, 255, 255, 0.2);
}

Usage:

<div class="content-auto hover:content-hidden"></div>
<p class="text-balance lg:text-pretty"></p>
<div class="bg-glass"></div>

Static utilities work with all variants automatically.

Functional Utilities with Integer Values

Create utilities that accept numeric values:

@utility mt-* {
  margin-top: calc(0.25rem * --value(integer));
}

@utility truncate-* {
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: --value(integer);
  overflow: hidden;
}

@utility text-stroke-* {
  -webkit-text-stroke-width: --value(integer) px;
}

Usage:

<div class="mt-5"></div>
<p class="truncate-3"></p>
<h1 class="text-stroke-2"></h1>

The --value(integer) function extracts the numeric value from the class name.

Theme-Based Utilities

Reference theme variables using --value(--namespace- *):

@theme {
  --tab-size-2: 2;
  --tab-size-4: 4;
  --tab-size-8: 8;
  --tab-size-github: 8;
}

@utility tab-* {
  tab-size: --value(--tab-size- *);
}

Usage:

<pre class="tab-2"><code>...</code></pre>
<pre class="tab-github"><code>...</code></pre>

Another example:

@theme {
  --aspect-square: 1 / 1;
  --aspect-video: 16 / 9;
  --aspect-portrait: 3 / 4;
}

@utility aspect-* {
  aspect-ratio: --value(--aspect- *);
}

Usage:

<img class="aspect-square" />
<video class="aspect-video" />
<div class="aspect-portrait"></div>

Multi-Value Utilities

Create utilities that accept multiple value types:

@utility text-stroke-* {
  -webkit-text-stroke-width: --value(integer) px;
  -webkit-text-stroke-color: --value(--color- *);
}

Usage:

<h1 class="text-stroke-2-blue-500">Stroked text</h1>
<h1 class="text-stroke-1-primary">Stroked with theme color</h1>

Another example:

@theme {
  --blur-sm: 4px;
  --blur-md: 8px;
  --blur-lg: 16px;
}

@utility backdrop-blur-* {
  backdrop-filter: blur(--value(--blur- *));
  backdrop-filter: blur(--value(integer) px);
}

Usage:

<div class="backdrop-blur-sm"></div>
<div class="backdrop-blur-12"></div>

Arbitrary Values Support

Support both theme values and arbitrary values:

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

Usage:

<pre class="tab-4">Theme value</pre>
<pre class="tab-[12]">Arbitrary value</pre>

The --value([integer]) function enables arbitrary value syntax with square brackets.

Complex Utility Examples

Gradient Text

@utility text-gradient-* {
  background: linear-gradient(to right, --value(--color- *), --value(--color- *, 2));
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
  background-clip: text;
}

Usage:

<h1 class="text-gradient-blue-500-purple-600">Gradient text</h1>

Grid Template Columns

@utility grid-cols-* {
  grid-template-columns: repeat(--value(integer), minmax(0, 1fr));
}

Usage:

<div class="grid grid-cols-3"></div>
<div class="grid grid-cols-5"></div>

Custom Line Clamp

@utility line-clamp-* {
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: --value(integer);
  overflow: hidden;
}

@utility line-clamp-none {
  display: block;
  -webkit-box-orient: horizontal;
  -webkit-line-clamp: none;
  overflow: visible;
}

Usage:

<p class="line-clamp-2 lg:line-clamp-3 xl:line-clamp-none"></p>

Custom Spacing Scale

@theme {
  --spacing-base: 0.25rem;
}

@utility gap-* {
  gap: calc(var(--spacing-base) * --value(integer));
}

@utility space-x-* > * + * {
  margin-left: calc(var(--spacing-base) * --value(integer));
}

Usage:

<div class="flex gap-6"></div>
<div class="flex space-x-4"></div>

Glassmorphism Utilities

@utility glass-* {
  background: rgba(255, 255, 255, --value(integer) / 100);
  backdrop-filter: blur(10px);
  border: 1px solid rgba(255, 255, 255, 0.2);
}

@utility glass-dark-* {
  background: rgba(0, 0, 0, --value(integer) / 100);
  backdrop-filter: blur(10px);
  border: 1px solid rgba(255, 255, 255, 0.1);
}

Usage:

<div class="glass-10"></div>
<div class="glass-dark-20"></div>

Utilities with Pseudo-Elements

@utility before-content-* {
  &::before {
    content: --value([string]);
    display: block;
  }
}

@utility after-content-* {
  &::after {
    content: --value([string]);
    display: block;
  }
}

Usage:

<div class="before:content-['★']">Star before</div>
<div class="after:content-['→']">Arrow after</div>

Complete Custom Utilities Library

@import 'tailwindcss';

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

@utility content-hidden {
  content-visibility: hidden;
}

@utility text-balance {
  text-wrap: balance;
}

@utility text-pretty {
  text-wrap: pretty;
}

@utility truncate-* {
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: --value(integer);
  overflow: hidden;
}

@utility bg-glass {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(10px);
  border: 1px solid rgba(255, 255, 255, 0.2);
}

@utility text-stroke-* {
  -webkit-text-stroke-width: --value(integer) px;
  -webkit-text-stroke-color: --value(--color- *);
}

@theme {
  --aspect-square: 1 / 1;
  --aspect-video: 16 / 9;
  --aspect-portrait: 3 / 4;
  --aspect-ultrawide: 21 / 9;
}

@utility aspect-* {
  aspect-ratio: --value(--aspect- *);
  aspect-ratio: --value([number]);
}

@theme {
  --tab-size-2: 2;
  --tab-size-4: 4;
  --tab-size-8: 8;
}

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

Why Use @utility Instead of @layer utilities

Don't do this:

@layer utilities {
  .my-button {
    padding: 1rem;
  }
}

Won't work with variants like hover:my-button.

Do this:

@utility my-button {
  padding: 1rem;
}

Works with all variants: hover:my-button, focus:my-button, lg:my-button.

Best Practices

1. Use @utility for variant support - Always use @utility instead of @layer utilities
2. Support arbitrary values - Include --value([type]) for flexibility
3. Use theme variables - Reference theme with --value(--namespace- *)
4. Name utilities semantically - Use clear, descriptive names
5. Group related utilities - Keep similar utilities together

Common Use Cases

• Custom CSS properties not in Tailwind
• Browser-specific prefixed properties
• Complex multi-property patterns
• Domain-specific utilities (e.g., print styles)
• Experimental CSS features

See Also

• RESEARCH.md section: "Advanced Patterns" → "Custom Utilities with @utility"