How to Offset the Underline on Text Elements in Tailwind CSS

Use the underline-offset utility class to control the distance between text and its underline, supporting static values like underline-offset-4, arbitrary values like underline-offset-[3px], and negative offsets like -underline-offset-2 to position the line above the text.

Tailwind CSS provides dedicated utilities for fine-tuning text decoration positioning without writing custom CSS. The framework implements the underline-offset utility as a functional utility that maps directly to the CSS text-underline-offset property. This article examines the implementation in the tailwindlabs/tailwindcss repository and demonstrates how to use these utilities to achieve precise underline positioning.

Where Underline Offset Utilities Are Defined

The underline-offset utility is implemented in packages/tailwindcss/src/utilities.ts as a functional utility (lines 1919‑1930). This definition handles static values, arbitrary values, supports negative offsets via the supportsNegative: true flag, and exposes a default auto value.

The basic underline utility (which adds text-decoration-line: underline) is defined nearby as a static utility at lines 3927‑3929 using staticUtility('underline', …).

The underlying CSS custom property --text-underline-offset is listed in the theme definition at packages/tailwindcss/src/theme.ts (lines 28‑30), enabling configuration via the Tailwind theme object.

Using Static and Arbitrary Offset Values

Tailwind generates static utility classes based on a predefined scale. The default scale includes values like 0, 1, 2, 4, and 8, generating classes such as underline-offset-2 and underline-offset-4. Each class outputs the CSS property text-underline-offset with the corresponding pixel value.

For precise control outside the default scale, use arbitrary values with bracket notation:

<p class="underline underline-offset-[5px]">
  Precise 5px offset from the text baseline
</p>

<p class="underline underline-offset-[0.1rem]">
  Offset using rem units for relative sizing
</p>

<p class="underline underline-offset-[calc(0.5em+2px)]">
  Complex calc expression for dynamic positioning
</p>

Negative Underline Offsets

The underline-offset utility supports negative values, allowing you to position the underline above the text rather than below it. This functionality is enabled by the supportsNegative: true flag in the utility definition at line 1919 of utilities.ts.

To apply a negative offset, prefix the class with a dash:

<p class="underline -underline-offset-2">
  This underline appears 2px above the text baseline.
</p>

Customizing the Offset Scale

You can extend the default offset scale in your tailwind.config.js to add reusable custom values that match your design system. This populates the static utility generation with your specific values:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      textUnderlineOffset: {
        // Adds underline-offset-12
        12: '12px',
        // Adds -underline-offset-12 for negative offset
        '-12': '-12px',
        // Adds precise 3px offset
        3: '3px',
      },
    },
  },
};

After configuration, Tailwind generates the corresponding static classes (e.g., underline-offset-12) automatically.

Creating Reusable Components with @apply

For consistent underline styling across your application, combine the utilities into a custom CSS class using the @apply directive:

/* src/styles/components.css */
.custom-link {
  @apply underline underline-offset-[3px] text-blue-600 hover:text-blue-800 transition-all;
}

<a href="#" class="custom-link">Styled link with custom offset</a>

This approach leverages the underlying text-underline-offset CSS property while maintaining Tailwind's utility-first workflow.

Summary

• The underline-offset utility controls the text-underline-offset CSS property, implemented in packages/tailwindcss/src/utilities.ts as a functional utility supporting static values, arbitrary values, and negative offsets.
• Use static classes like underline-offset-2 or underline-offset-4 for standard offsets, or arbitrary values like underline-offset-[3px] for precise control.
• Apply negative offsets with -underline-offset-2 to position the underline above the text.
• Extend the textUnderlineOffset theme key in tailwind.config.js to add custom static values to your design system.
• Combine utilities with @apply to create reusable component classes for consistent underline styling.

Frequently Asked Questions

How do I change the underline offset distance in Tailwind CSS?

Use the underline-offset utility class followed by a number from the default scale (e.g., underline-offset-2, underline-offset-4) or an arbitrary value in brackets (e.g., underline-offset-[5px]). These classes map to the CSS text-underline-offset property and are defined in packages/tailwindcss/src/utilities.ts.

Can I move the underline above the text instead of below it?

Yes. The underline-offset utility supports negative values via the supportsNegative: true flag in its source definition. Prefix the class with a dash, such as -underline-offset-2 or -underline-offset-4, to offset the underline in the opposite direction, positioning it above the text baseline.

How do I add custom underline offset values to my Tailwind configuration?

Extend the textUnderlineOffset theme key in your tailwind.config.js file. For example, adding 12: '12px' under theme.extend.textUnderlineOffset generates the underline-offset-12 class. This customization populates the static utility classes defined in the Tailwind theme at packages/tailwindcss/src/theme.ts.

What is the difference between underline and underline-offset in Tailwind CSS?

The underline utility is a static utility that adds text-decoration-line: underline to enable the underline decoration. The underline-offset utility is a functional utility that controls the distance between the text and the underline using the text-underline-offset CSS property. You must use both classes together: underline enables the decoration, while underline-offset adjusts its vertical position.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}