How CSS text-underline-offset Controls Underlines

The CSS text-underline-offset property provides precise control over typography by adjusting the vertical distance between text and its underline. Traditionally, browsers determined this spacing automatically, often placing underlines too close to the baseline or causing awkward collisions with font descenders like the tails of "g", "y", and "p". By using text-underline-offset, web designers and developers can fine-tune underline positioning to enhance readability, create custom link styles, and establish better visual hierarchy without relying on borders or pseudo-elements.

How the Property Works

The text-underline-offset property specifies the offset distance for text decorations applied as underlines. It only works when an underline is present, typically set via text-decoration: underline or text-decoration-line: underline.

The property accepts the following primary values:

  • auto: The default value. The browser calculates an appropriate offset based on the font metrics or platform defaults.
  • Length units (px, em, rem, etc.): Sets a fixed or scalable distance between the text baseline and the underline.
  • Percentage values (%): Sets the offset as a percentage of 1em (the element's font size).
  • Global values: Standard CSS keywords such as inherit, initial, revert, and unset.

Direction and Movement

The offset behaves relative to the text baseline:

  • Positive values move the underline further downward, away from the text baseline in horizontal writing modes. For example, text-underline-offset: 4px; pushes the underline lower, creating breathing room beneath descenders.
  • Negative values move the underline upward, closer to or across the text baseline. Setting a negative offset can pull the underline directly across the text, resembling a strikethrough if offset far enough.
  • Zero (0) places the underline precisely at the font's baseline.

Syntax and Implementation

To adjust an underline, combine the offset property with standard text decoration rules:

a {
  text-decoration-line: underline;
  text-decoration-color: #0066cc;
  text-decoration-thickness: 2px;
  text-underline-offset: 0.25em;
}

Using relative units like em or percentages is often best practice because the spacing scales dynamically if the font size changes across different viewports or components.

Interaction with Other Text Decoration Properties

text-underline-offset is part of the modern CSS Text Decoration Module Level 4 and is distinct from the text-decoration shorthand in older specifications. While it adjusts the gap, it works alongside:

  • text-decoration-thickness: Controls the stroke weight of the underline without affecting its position.
  • text-decoration-skip-ink: Determines whether the line automatically breaks to avoid cutting through descenders. Even with text-decoration-skip-ink: auto, increasing text-underline-offset can eliminate breaks entirely by dropping the line below the descenders.

Inheritance and Scope

The text-underline-offset property is inherited by child elements. However, if a parent element generates an underline, child elements cannot independently offset that specific line. To modify the offset on a specific nested element, the underline must be declared directly on that element rather than inherited from a parent container.