CSS text-decoration playground

Educational guide to text-decoration

Decorate text while keeping it readable

An underline communicates an action, and a strike can express a change. Learn to choose line, style, color and thickness, separate decoration from characters and keep links recognizable.

Back to the playground

Mental model

Decoration is drawn on each line of text; it is not a box border and does not change the characters.

Text, stroke and spacingConceptual diagram, without actual font measurements. Numbers connect ink, stroke thickness and underline spacing; they do not represent controls.

1 · Character inkThe font draws the letters and their descenders, such as those in g or y.
2 · Decoration thicknesstext-decoration-thickness controls the stroke, not the letter weight.
3 · Underline spacingtext-underline-offset moves underline; it does not move overline or line-through.

text-decoration adds strokes to text. underline puts a line below, overline above and line-through across the letters in horizontal writing. You can combine these lines with spaces. none creates no new decoration; it cannot be combined with the other lines.

Appearance does not add HTML semantics. Underlined text does not become a link: use a with href for navigation. If a strike means deleted content, use del; s may suit content that is no longer accurate. Explain the change in words when needed.

Lines, styles and thickness

Choose what to draw, then how to draw it.

solid, double, dotted, dashed and wavy change the stroke pattern. All lines in one decoration share style, color and thickness. To combine a solid underline and a dotted overline, apply decorations on separate elements.

text-decoration-color is independent of color: it changes the line, not the letters. Its initial currentColor value follows the text color of the element that originates the decoration. Keep enough contrast between text, stroke and background, including in dark mode.

auto lets the browser choose thickness. from-font uses a font metric, falling back to auto when unavailable. A length sets thickness: px, rem and em use different references; 0.08em relates to the text size. Percentages are also calculated relative to 1em.

text-decoration: underline solid currentColor 0.08em;

text-decoration-line: underline;
text-decoration-style: solid;
text-decoration-color: currentColor;
text-decoration-thickness: 0.08em;

The shorthand resets omitted parts. Writing text-decoration: underline after a custom thickness restores thickness to auto. Use text-decoration-line to change only the line, or specify the full decoration again.

Five styles with the same text and thickness

solid · Typography with g, j, p and y

double · Typography with g, j, p and y

dotted · Typography with g, j, p and y

dashed · Typography with g, j, p and y

wavy · Typography with g, j, p and y

All five samples use underline, currentColor and 2px, generated with the playground helper. Only the style changes. Labels identify the pattern; these samples are text, not links.

Five styles with the same text and thickness

HTML

<div class="decoration-guide-styles">
  <p class="decoration-guide-solid">solid · Typography with g, j, p and y</p>
  <p class="decoration-guide-double">double · Typography with g, j, p and y</p>
  <p class="decoration-guide-dotted">dotted · Typography with g, j, p and y</p>
  <p class="decoration-guide-dashed">dashed · Typography with g, j, p and y</p>
  <p class="decoration-guide-wavy">wavy · Typography with g, j, p and y</p>
</div>

CSS

:root {
  color-scheme: light dark;
}

.decoration-guide-styles {
  display: grid;
  gap: 1.5rem;
  color: light-dark(oklch(0.22 0.01 95), oklch(0.95 0.01 95));

  p {
    margin: 0;
    font: 600 1.25rem/1.8 system-ui, sans-serif;
    overflow-wrap: anywhere;
  }
}

.decoration-guide-solid {
  text-decoration: underline solid currentColor 2px;
}

.decoration-guide-double {
  text-decoration: underline double currentColor 2px;
}

.decoration-guide-dotted {
  text-decoration: underline dotted currentColor 2px;
}

.decoration-guide-dashed {
  text-decoration: underline dashed currentColor 2px;
}

.decoration-guide-wavy {
  text-decoration: underline wavy currentColor 2px;
}

Stroke spacing and continuity

Distance from letters and interruptions around their ink are separate choices.

text-underline-offset moves the underline from its original position. Use a moderate distance and check multiple lines: increasing offset does not reserve layout space. Too much may bring the stroke near the next line; keep readable line-height and avoid clipping.

text-decoration-skip-ink: auto allows underline and overline to break near ink. none keeps the stroke when crossing characters. It does not control line-through. Results depend on font and position: without crossings, auto and none may look the same.

Avoid ink, cross it or move the underline away

skip-ink: auto · offset: auto

Typography with g, j, p and y

skip-ink: none · offset: auto

Typography with g, j, p and y

skip-ink: auto · offset: 0.25em

Typography with g, j, p and y

The three samples keep the same font, thickness and line height. The second changes only skip-ink to none; the third keeps auto and adds a 0.25em offset. Compare g, j, p and y. None of the samples simulates an unsupported browser.

Avoid ink, cross it or move the underline away

HTML

<div class="decoration-guide-spacing">
  <div>
    <p>skip-ink: auto · offset: auto</p>
    <p class="decoration-guide-ink">Typography with g, j, p and y</p>
  </div>
  <div>
    <p>skip-ink: none · offset: auto</p>
    <p class="decoration-guide-ink is-continuous">Typography with g, j, p and y</p>
  </div>
  <div>
    <p>skip-ink: auto · offset: 0.25em</p>
    <p class="decoration-guide-ink is-offset">Typography with g, j, p and y</p>
  </div>
</div>

CSS

:root {
  color-scheme: light dark;
}

.decoration-guide-spacing {
  display: grid;
  gap: 2rem;
  color: light-dark(oklch(0.22 0.01 95), oklch(0.95 0.01 95));

  p {
    margin: 0;
    font: 1rem/1.6 system-ui, sans-serif;
  }

  .decoration-guide-ink {
    margin-block-start: 0.75rem;
    font: 600 1.5rem/1.8 Georgia, serif;
    text-decoration: underline;
    text-decoration-thickness: 0.08em;
    text-underline-offset: auto;
    text-decoration-skip-ink: auto;
    overflow-wrap: anywhere;

    &.is-continuous {
      text-decoration-skip-ink: none;
    }

    &.is-offset {
      text-underline-offset: 0.25em;
    }
  }
}

Offset and skip-ink are outside the shorthand and need separate declarations. Do not automatically replace underlines with border-block-end: a border follows the box and does not reproduce decoration around characters or the fragments of a multiline link.

Parent decoration and descendant text

Visual continuity is different from normal property inheritance.

Parent decoration is also drawn over inline descendant text. Although text-decoration is not inherited, a span with none does not erase the stroke originating on its parent. A child can add its own decoration; it does not change the style or color of the existing parent decoration.

Why none does not remove the parent underline

Decoration on the parent · child uses none

This text includes a central fragment within the sentence.

Decoration only on selected fragments

This text includes a central fragment within the sentence.

Above, the span declares none and the parent line still runs under the full sentence. Below, only the outer fragments originate underlines; the middle text has none. The difference remains when the sentence wraps.

Why none does not remove the parent underline

HTML

<div class="decoration-guide-continuity">
  <div>
    <p>Decoration on the parent · child uses none</p>
    <p class="decoration-guide-parent">This text includes <span>a central fragment</span> within the sentence.</p>
  </div>
  <div>
    <p>Decoration only on selected fragments</p>
    <p class="decoration-guide-targeted"><span>This text includes</span> a central fragment <span>within the sentence.</span></p>
  </div>
</div>

CSS

:root {
  color-scheme: light dark;
}

.decoration-guide-continuity {
  display: grid;
  gap: 2rem;
  color: light-dark(oklch(0.22 0.01 95), oklch(0.95 0.01 95));

  p {
    margin: 0;
    font: 1rem/1.6 system-ui, sans-serif;
  }

  .decoration-guide-parent,
  .decoration-guide-targeted {
    margin-block-start: 0.75rem;
    font-size: 1.25rem;
    line-height: 1.8;
    overflow-wrap: anywhere;
  }
}

.decoration-guide-parent {
  text-decoration: underline;

  span {
    text-decoration: none;
  }
}

.decoration-guide-targeted span {
  text-decoration: underline;
}

Apply decoration to the element that should originate it, instead of trying to cancel it from children. Atomic inline elements such as inline-block have different propagation boundaries; changing display just to hide a stroke also changes layout and line breaks.

Recognizable links in a paragraph

Decoration helps reveal navigation before hover or focus.

Keep a visible cue beyond color for links within text. A persistent underline is a clear option for people who cannot distinguish colors. Hover can reinforce it, but should not be the only way to discover the link; focus needs its own outline.

A real link with an underline and visible focus

To align typographic boxes, read the text-box guide and leave room for accents and descenders.

The link opens the text-box guide in the current language. It stays underlined at rest, becomes thicker on hover and shows an outline on keyboard focus. If thickness or spacing adjustments are ignored, it remains an underlined link.

A real link with an underline and visible focus

HTML

<p class="decoration-guide-paragraph">
  To align typographic boxes, read
  <a href="/en/css/texts/text-box/#guide">the text-box guide</a>
  and leave room for accents and descenders.
</p>

CSS

:root {
  color-scheme: light dark;
}

.decoration-guide-paragraph {
  margin: 0;
  color: light-dark(oklch(0.22 0.01 95), oklch(0.95 0.01 95));
  font: 1.125rem/1.8 system-ui, sans-serif;
  overflow-wrap: anywhere;

  a {
    color: light-dark(oklch(0.46 0.14 261), oklch(0.82 0.18 261));
    text-decoration: underline;
    text-decoration-thickness: 0.08em;
    text-underline-offset: 0.2em;
    text-decoration-skip-ink: auto;

    &:hover {
      text-decoration-thickness: 0.14em;
    }

    &:focus-visible {
      outline: 2px solid currentColor;
      outline-offset: 3px;
    }
  }
}

Test long names, line breaks, fallback fonts and enlarged text. A very thick or close stroke makes reading harder; a line too far away loses its association with the link. Review contrast and readability in your target themes and browsers.

Common mistakes

Check the active line, cascade and stroke origin.

Style or thickness produces no line

Expected result: See a custom underline.
Cause: text-decoration-line remains none; style and thickness do not activate a line.
Solution: Declare underline or another line alongside style and thickness.

none on a child does not remove the underline

Expected result: Leave a fragment undecorated.
Cause: Decoration originates on the parent and is drawn over the inline descendant.
Solution: Remove the parent decoration and apply it only to the required fragments.

Custom thickness returns to auto

Expected result: Change the line while keeping thickness.
Cause: A later shorthand omits thickness and restores its initial value.
Solution: Change text-decoration-line or include thickness in the final shorthand.

The strike does not move with offset

Expected result: Move line-through away from the letters.
Cause: text-underline-offset only affects underline, not the other lines.
Solution: Use offset for underlines; review strike font and thickness without expecting that movement.

The link is only distinguishable on hover

Expected result: Recognize navigation within a paragraph.
Cause: The persistent cue has been removed, relying on hover or color.
Solution: Keep an underline or another visible cue and a separate keyboard focus indicator.

Support and compatibility

Check each property and value, beyond the basic shorthand.

MDN identifies text-decoration, thickness, underline-offset and skip-ink as widely available, with differences in some parts. These recipes use common lines and styles and skip-ink auto/none. Do not extend that support to all or new draft syntax.

The link recipe starts with text-decoration: underline and adds thickness and spacing in separate declarations. Ignoring an enhancement preserves the base underline. @supports checks syntax; it does not guarantee identical rendering or readability with every font.