CSS text-underline-offset Property

What You’ll Learn

The text-underline-offset property controls how far an underline sits from text — useful for links, headings, and refined typography.

Introduction

The text-underline-offset property in CSS allows developers to control the position of the underline set by the text-decoration property.

This property is particularly useful when you want to adjust the space between the text and its underline, enhancing readability or achieving specific design effects.

Definition and Usage

Use text-underline-offset when a default underline feels too tight against letters — especially on links, underlined headings, or text with descenders like “g” and “y”.

📝 Syntax

The syntax for the text-underline-offset property is straightforward. It accepts length values, such as pixels (px), points (pt), or percentages (%).

element {
  text-underline-offset: length;
}

Here, length is the distance by which the underline is offset from the default position of the text baseline.

Basic Example

p {
  text-decoration: underline;
  text-underline-offset: 5px;
}

Syntax Rules

• Accepts auto or a length value (px, em, rem, %).
• Positive values push the underline farther from the text.
• Negative values pull the underline closer to the baseline.
• Only affects underlines — pair with text-decoration-line: underline or shorthand text-decoration: underline.
• The property is inherited.

Related Properties

• text-decoration — shorthand for underline, color, style, and thickness
• text-decoration-line — sets which decoration lines appear
• text-underline-position — controls underline placement relative to the text
• text-decoration-thickness — sets underline stroke width

🎯 Default Value

The default value of text-underline-offset is auto, which means the browser determines the offset automatically based on font metrics and text decoration settings.

💎 Property Values

The text-underline-offset property accepts a keyword or length value.

When to Use text-underline-offset

text-underline-offset is helpful whenever underline spacing matters:

• Navigation links — Add breathing room so underlines do not collide with descenders.
• Headings — Create elegant underlined titles with extra gap below letters.
• Custom link styles — Fine-tune offset alongside color and thickness.
• Accessibility — Improve clarity when underline thickness is increased.

Examples Gallery

In this example, we’ll adjust the underline offset for a paragraph of text.

<style>
  p {
    text-decoration: underline;
    text-underline-offset: 5px;
  }
</style>

<h1>Text with Custom Underline Offset</h1>
<p>This paragraph has a custom underline offset.</p>

a {
  text-decoration-line: underline;
  text-decoration-color: #2563eb;
  text-decoration-thickness: 2px;
  text-underline-offset: 4px;
  color: #1e40af;
}

.default {
  text-decoration: underline;
  text-underline-offset: auto;
}

.spaced {
  text-decoration: underline;
  text-underline-offset: 8px;
}

h2 {
  text-decoration-line: underline;
  text-decoration-color: #dc2626;
  text-underline-offset: 0.2em;
  font-size: 1.75rem;
}

♿ Accessibility

• Do not remove underline meaning — Links should remain identifiable; offset adjusts spacing, not presence.
• Pair with sufficient contrast — Use text-decoration-color that meets contrast guidelines.
• Avoid negative offsets on body text — Underlines overlapping letters hurt readability.
• Test with thick underlines — Larger text-decoration-thickness values often need more offset.

The underline styling stack

Modern underline styling often combines line, color, thickness, and offset. Use the shorthand or longhand properties together for full control.

a {
  text-decoration-line: underline;
  text-decoration-color: currentColor;
  text-decoration-thickness: 2px;
  text-underline-offset: 3px;
}

💡 Best Practices