CSS text-underline-position Property

What You’ll Learn

The text-underline-position property controls where underlines are drawn — below text in horizontal layouts or beside text in vertical writing modes.

Introduction

The text-underline-position property in CSS allows web developers to control the position of underlines for text.

This property is particularly useful for fine-tuning the appearance of underlined text, especially in different writing modes and scripts. It can enhance readability and aesthetics by allowing more precise control over underline placement.

Definition and Usage

Use text-underline-position when default underlines collide with descenders (like “g” and “y”) or when vertical text needs the line on a specific side of the characters.

📝 Syntax

The syntax for the text-underline-position property is straightforward. It can be applied to any element containing text.

element {
  text-underline-position: value;
}

Here, value can be one of several keywords that define the position of the underline.

Basic Example

p {
  text-underline-position: under;
  text-decoration: underline;
}

Syntax Rules

• Keyword values include auto, under, left, right, and under left.
• left and right apply mainly in vertical writing modes.
• under left combines placement for vertical text layouts.
• Requires an underline from text-decoration or text-decoration-line.
• The property is inherited.

Related Properties

• text-underline-offset — adjusts distance between text and underline
• text-decoration — shorthand for underline and other lines
• writing-mode — sets horizontal or vertical text flow
• text-decoration-thickness — controls underline stroke width

🎯 Default Value

The default value of the text-underline-position property is auto, which lets the browser decide the most appropriate position for the underline based on the font and text.

💎 Property Values

The text-underline-position property accepts keyword values that define underline placement.

When to Use text-underline-position

text-underline-position is the right choice when underline placement affects clarity:

• Links with descenders — Use under so lines do not cut through letters like “g”.
• Vertical layouts — Place underlines on left or right in vertical writing modes.
• Multilingual sites — Let auto respect language-specific typography when appropriate.
• Design systems — Standardize underline behavior alongside offset and thickness.

Examples Gallery

In this example, we’ll change the underline position of some text to be below the text.

<style>
  p {
    text-underline-position: under;
    text-decoration: underline;
  }
</style>

<h1>Text with Custom Underline Position</h1>
<p>This is a paragraph with the underline positioned under the text.</p>

.auto-line {
  text-decoration: underline;
  text-underline-position: auto;
}

.under-line {
  text-decoration: underline;
  text-underline-position: under;
}

.vertical {
  writing-mode: vertical-rl;
  text-decoration: underline;
  text-underline-position: left;
}

a {
  text-decoration-line: underline;
  text-underline-position: under;
  text-underline-offset: 3px;
  text-decoration-thickness: 2px;
  color: #1d4ed8;
}

♿ Accessibility

• Keep links identifiable — Position adjusts placement; do not remove underlines from links without another clear indicator.
• Improve readability — under can help when thick underlines overlap letter shapes.
• Test with real content — Verify descenders and multilingual text in your chosen typeface.
• Combine with contrast — Use sufficient color contrast for underlines and link text.

position vs offset

text-underline-position chooses where the line is drawn (below, left, right). text-underline-offset moves it farther by a specific distance. Use both for precise control.

a {
  text-decoration-line: underline;
  text-underline-position: under;
  text-underline-offset: 4px;
}

💡 Best Practices