How to Use CSS text-decoration-thickness

This article provides a comprehensive overview of the CSS text-decoration-thickness property, explaining its core function, supported values, and practical implementation in modern web design. Readers will learn how this property controls the stroke width of text decoration lines—such as underlines and strikethroughs—improving typography aesthetics and reading accessibility without resorting to custom border hacks.

What Does text-decoration-thickness Do?

The text-decoration-thickness property in CSS sets the stroke thickness of decorative lines applied to text elements. These lines include underlines, overlines, and line-throughs (strikethroughs) created using text-decoration or text-decoration-line.

Historically, developers relied on border-bottom or pseudo-elements to create custom-weight underlines because standard CSS underlines were fixed to the browser's default thickness. The text-decoration-thickness property eliminates the need for these workarounds, allowing direct and native control over line weight.

Accepted Values

The property accepts predefined keywords, fixed length units, and percentage values:

• auto (Default): The browser chooses an appropriate stroke thickness based on the font and font size.
• from-font: If the active font file contains preferred thickness metrics, the browser will use them. If no font-specified preference exists, it falls back to auto.
• Length units: Explicit units such as pixels (px), relative units (em, rem), or viewport units (vw).
• Percentages: A percentage value calculated relative to 1em of the current font size (e.g., 10% on a 16px font equals a 1.6px thickness).

Code Examples

1. Setting Explicit Lengths

/* Sets a thin, subtle underline */
a.subtle-link {
  text-decoration-line: underline;
  text-decoration-thickness: 1px;
}

/* Sets a bold, prominent strikethrough */
span.sale-price {
  text-decoration-line: line-through;
  text-decoration-thickness: 3px;
}

2. Using Relative Values

Using em or percentages ensures the line scales proportionally if the font size changes dynamically across screen sizes:

h1 {
  text-decoration-line: underline;
  text-decoration-thickness: 0.15em;
}

3. Shorthand Usage

text-decoration-thickness is included in the text-decoration shorthand. It can be defined alongside line type, color, and style:

a {
  /* line | style | color | thickness */
  text-decoration: underline solid #0056b3 2px;
}

Pairing with text-underline-offset

text-decoration-thickness is frequently paired with text-underline-offset. Increasing the thickness of an underline can cause it to collide with text descenders (the descending parts of letters like g, j, p, and y). Applying an offset pushes the line downward, maintaining legibility:

a {
  text-decoration: underline;
  text-decoration-thickness: 2px;
  text-underline-offset: 4px;
}

Key Considerations

• Inheritance: text-decoration-thickness does not strictly inherit like standard typographic properties; child elements will usually share the decoration line drawn across the parent element.
• Accessibility: Ensure that decorative lines are thick enough to be easily visible to users with low vision, particularly on interactive links, while avoiding excessive thickness that could obscure the text itself.