text-decoration-thickness

The text-decoration-thickness property in CSS sets the stroke thickness of the decoration line that is used on text in an element. The text-decoration-line value needs to be either underline, line-through, or overline to reflect the thickness property.

.text {
  text-decoration-line: underline;
  text-decoration-thickness: 2px;
}

Syntax

text-decoration-thickness: auto | from-font | <length> | <percentage>

Values

• auto: (Default) Allows the browser to specify an appropriate thickness for the text decoration line.
• from-font: If the first available font has metrics specifying a preferred thickness, it uses that thickness; otherwise it behaves like the auto value.
• <length>: Any valid length with a unit specifies the thickness of text decoration lines as a fixed length. This replaces any information in the font and the browser default.
• percentage: Specifies the thickness of text decoration lines as a percentage of 1em in the element’s font.
• initial: The default setting of the property, which is auto.
• inherit: Adopts the decoration thickness value of the parent.
• unset: Removes the current thickness from the element.

Demo

Change the value of text-decoration-thickness in the following demo to see how the property affects the text decoration of the element:

It is constant for descendants

After setting a decoration for an element, all its children will have that decoration too. Now imagine we want to change the thickness of the decoration for one of the children:

p {
  text-decoration-line: underline;
  text-decoration-color: green;
  text-decoration-thickness: 0.2em;
}


p span {
  text-decoration-thickness: 0.1em; /* Doesn't work */
}

This doesn’t work because the decoration thickness specified by ancestor elements cannot be overridden. For this to work, a decoration specificity needs to be set for the element itself:

p {
  text-decoration-line: underline;
  text-decoration-color: green;
  text-decoration-thickness: 0.2em;
}

p span {
  text-decoration-line: underline;
  text-decoration-color: green;
  text-decoration-thickness: 0.1em; /* It works! */
}

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.

p {
  text-decoration-thickness: 20%;
}


p span {
  font-size: 20px;
  text-decoration-line: underline;
  text-decoration-thickness: inherit; /* = 20% */  
}

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. That means it doesn’t scale with the change in the font. On the right side, however, the text inherits a relative value (in this case 20%); therefore the thickness scales with the change in the font.

While the current working draft of the specification references percentage values for text-decoration-thickness, actual support is currently limited to Firefox.

Using with text-decoration

The current working draft of the CSS Text Decoration Module Level 4 specification includes text-decoration-thickness as a value in the text-decoration shorthand property.

.link {
  text-decoration: underline solid green 1px;
}


/* The longhand equivalent */
.link { 
  text-decoration-line: underline;
  text-decoration-style: solid;
  text-decoration-color: green,
  text-decoration-thickness: 1px;
}

While text-decoration is well supported, support for the inclusion of text-decoration-thickness is currently limited to Firefox.

Browser support

Feature	IE	Edge	Firefox	Chrome	Safari	Opera
Property	No	No	70	No	12.1	No
Percentages	No	No	76	No	No	No
Shorthand	No	No	70	No	No	No

Feature	Android Chrome	Android Firefox	Android Browser	iOS Safari	Opera Mini
Property	No	No	No	12.2	No
Percentages	No	No	No	No	No
Shorthand	No	No	No	No	No

Notes

• The property used to be called text-decoration-width, but was updated in the 2019 working draft of the CSS Text Decoration Module Level 4 specification.
• The browser must use a minimum thickness of 1 device pixel.

Related