text-underline-offset

CSS Almanac → Properties → T → text-underline-offset

Mojtaba Seyedi on May 18, 2020 (Updated on Aug 2, 2021)

The text-underline-offset property in CSS sets the distance of text underlines from their initial position.

.element {
  text-underline-offset: 0.5em;
}

Once you apply an underline for an element using text-decoration with the value of underline, you can say how far that line should be from your text using the text-underline-offset property.

Values

auto: (Default) The browser will specify an appropriate offset for underlines.
<length>: Any valid length with a specified unit (including negative values). This replaces any information in the font and the browser default.
percentage: Specifies the offset of underlines as a percentage of 1em in the element’s font.
initial: The default setting of the property, which is auto.
inherit: Adopts the underline offset value of the parent.
unset: Removes the current offset from the element.

Demo

In the following demo you can change the value of text-underline-offset to see how it affects the text decoration of the element:

Notes

text-underline-offset is not part of the shorthand of text-decoration.
It doesn’t work on other text-decoration lines, such as line-through or overline.
Negative values are accepted, which offsets the underline inward.

It is constant for the descendants

Once you set a decoration for an element, all its children will have that decoration too. Now imagine you want to change the offset of the underline for one of the children:

p {
  text-decoration: underline;
  text-underline-offset: 0.5em;
}
 
p span {
  text-underline-offset: 1.5em; /* Doesn't work */
}

This doesn’t work because you cannot override an offset of an underline specified by ancestor elements. For this to work, you need to set an underline specificity for the element itself:

p {
  text-decoration: underline;
  text-underline-offset: 0.5em;
}
 
p span {
  text-decoration: underline;
  text-underline-offset: 1.5em; /* It works! */
}

Using em is recommended

The benefit of using a relative value like em is that the offset will scale with the change of the font-size value. On the other hand, if you use a fixed length unit (e.g. pixels), the offset won’t adjust to the changes and it may not be the distance that you would like to have for your text:

Percentage and the cascade

For this property, a length will inherit as a fixed value, and will not scale with the font. On the other hand, a percentage will inherit as a relative value and, therefore, scale with changes in the font as it inherits.

The following demo shows the comparison between using em and percentage values in the case of inheritance and, as you can see, on the left side (in which we are using em) the inherited value is a fixed length. You can check the computed value in your DevTools. That means it doesn’t scale with the change in the font. On the right side, however, the texts inherit a relative value (in this case 100%); therefore the offset scales with the change in the font:

Writing Modes and text-underline-position

Having a vertical writing mode has an effect on the position of the underline. That will change the direction of the offset applied on the element. Play with the values in the following demo: