text-decoration-thickness

Avatar of Mojtaba Seyedi
Mojtaba Seyedi on (Updated on )

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

FeatureIEEdgeFirefoxChromeSafariOpera
PropertyNoNo70No12.1No
PercentagesNoNo76NoNoNo
ShorthandNoNo70NoNoNo
FeatureAndroid ChromeAndroid FirefoxAndroid BrowseriOS SafariOpera Mini
PropertyNoNoNo12.2No
PercentagesNoNoNoNoNo
ShorthandNoNoNoNoNo
Source: caniuse

Notes