# How to Offset the Underline on Text Elements in Tailwind CSS

> Learn how to offset underlines in Tailwind CSS with the underline offset utility. Control distance with static, arbitrary, and negative values for precise text styling.

- Repository: [Tailwind Labs/tailwindcss](https://github.com/tailwindlabs/tailwindcss)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/tailwindlabs/tailwindcss/blob/main/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`](https://github.com/tailwindlabs/tailwindcss/blob/main/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:

```html
<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`](https://github.com/tailwindlabs/tailwindcss/blob/main/utilities.ts).

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

```html
<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`](https://github.com/tailwindlabs/tailwindcss/blob/main/tailwind.config.js) to add reusable custom values that match your design system. This populates the static utility generation with your specific values:

```js
// 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:

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

```

```html
<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`](https://github.com/tailwindlabs/tailwindcss/blob/main/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`](https://github.com/tailwindlabs/tailwindcss/blob/main/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`](https://github.com/tailwindlabs/tailwindcss/blob/main/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`](https://github.com/tailwindlabs/tailwindcss/blob/main/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`](https://github.com/tailwindlabs/tailwindcss/blob/main/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.