Add docs for the CSS text-decoration-inset property #41901

chrisdavidmills · 2025-11-11T12:41:13Z

Description

Firefox 146 onwards has the text-decoration-inset property enabled by default (see https://bugzilla.mozilla.org/show_bug.cgi?id=1993043; it was called text-decoration-trim, but it got renamed). I've tested it, and it doesn't work in Chrome/Safari yet.

This PR adds a reference page for the new property, and links to it from the text decoration module page.

Motivation

Additional details

Related issues and pull requests

github-actions · 2025-11-11T12:42:58Z

Preview URLs

Flaws (41)

URL: /en-US/docs/Web/CSS/Guides/Text_decoration
Title: CSS text decoration
Flaw count: 34

macros:
- Macro produces link /en-US/docs/Web/CSS/text-decoration-skip-ink which is a redirect
- Macro produces link /en-US/docs/Web/CSS/text-underline-offset which is a redirect
- Macro produces link /en-US/docs/Web/CSS/text-shadow which is a redirect
- Macro produces link /en-US/docs/Web/CSS/color which is a redirect
- Macro produces link /en-US/docs/Web/CSS/text-decoration which is a redirect
- and 29 more flaws omitted

URL: /en-US/docs/Web/CSS/Reference/Properties/text-decoration-inset
Title: text-decoration-inset
Flaw count: 7

macros:
- Macro produces link /en-US/docs/Web/CSS/length which is a redirect
- Macro produces link /en-US/docs/Web/CSS/length which is a redirect
- Macro produces link /en-US/docs/Web/CSS/text-decoration which is a redirect
- Macro produces link /en-US/docs/Web/CSS/text-decoration which is a redirect
- Macro produces link /en-US/docs/Web/CSS/text-decoration which is a redirect
- and 1 more flaws omitted
unknown:
- Error: could not find syntax for this item

External URLs (1)

URL: /en-US/docs/Web/CSS/Reference/Properties/text-decoration-inset
Title: text-decoration-inset

https://www.w3.org/TR/clreq/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-11-13 10:03:05)

files/en-us/web/css/reference/properties/text-decoration-inset/index.md

estelle

Looks good. Just a few suggestions.

files/en-us/web/css/reference/properties/text-decoration-inset/index.md

estelle · 2025-11-13T00:47:55Z

files/en-us/web/css/reference/properties/text-decoration-inset/index.md

+
+## Description
+
+The `text-decoration-inset` property allows you to adjust the start and/or end points of a text container's text decoration, as set by the {{cssxref("text-decoration")}} shorthand and associated longhand properties. This is useful for creating effects where you want the text decoration to be inset or outset from the text itself, or shifted in position. See [Basic use cases](/en-US/docs/Web/CSS/Reference/Properties/text-decoration-inset#basic_use_cases) for an example of each.


Suggested change

The `text-decoration-inset` property allows you to adjust the start and/or end points of a text container's text decoration, as set by the {{cssxref("text-decoration")}} shorthand and associated longhand properties. This is useful for creating effects where you want the text decoration to be inset or outset from the text itself, or shifted in position. See [Basic use cases](/en-US/docs/Web/CSS/Reference/Properties/text-decoration-inset#basic_use_cases) for an example of each.

By default, an element's text decoration is the same size as the rendered text. The `text-decoration-inset` property allows you to adjust the start and/or end points of a text container's text decoration, as set by the {{cssxref("text-decoration")}} shorthand and associated longhand properties. This is useful for creating effects where you want the text decoration to be inset or outset from the text itself, or shifted in position. See [Basic use cases](/en-US/docs/Web/CSS/Reference/Properties/text-decoration-inset#basic_use_cases) for an example of each.

Saying this is a good idea, but I've shifted the order of the text around a bit, so that the first sentence says:

By default, an element's text decoration, as set by the {{cssxref("text-decoration")}} shorthand and associated longhand properties, is the same size as the rendered text.

I think it reads better this way.

estelle · 2025-11-13T00:50:25Z

files/en-us/web/css/reference/properties/text-decoration-inset/index.md

+
+The `text-decoration-inset` property can also take the `auto` keyword, which causes the browser to choose a value to ensure that, if two decorated text boxes appear side-by-side, a gap is created between them so they do not appear to have a single text decoration. The `auto` value is particularly important when rendering Chinese text, as underlining is used to [punctuate proper nouns](https://www.w3.org/TR/clreq/#id88), and adjacent proper nouns should have separate underlines. See [Effect of the `auto` value](/en-US/docs/Web/CSS/Reference/Properties/text-decoration-inset#effect_of_the_auto_value) for an example.
+
+The `auto` value does not have the same effect as a `text-decoration-inset` value of `0` (which is the initial value) — `0` causes there to be no space between decorations.


Suggested change

The `auto` value does not have the same effect as a `text-decoration-inset` value of `0` (which is the initial value) — `0` causes there to be no space between decorations.

The `auto` value does not have the same effect as a `text-decoration-inset` value of `0`. The initial value `0` causes there to be no space between decorations.

Makes sense, but I've reordered this to:

The auto value does not have the same effect as the initial value 0. Setting text-decoration-inset to 0 causes there to be no space between decorations. I thought it better to mention it is the initial value on the first mention of 0, not the second.

files/en-us/web/css/reference/properties/text-decoration-inset/index.md

estelle · 2025-11-13T01:02:16Z

files/en-us/web/css/reference/properties/text-decoration-inset/index.md

+  text-decoration-inset: 1em -1em;
+}
+```
+


Let's add something like the following to both examples as "css hidden":

@supports not (text-decoration-inset: auto) { body::before { content: "Your browser doesn't support the `text-decoration-inset` property."; background-color: wheat; display: block; width: 100%; text-align: center; } }

Great idea. I've tweaked the styles a little bit and added the block to both examples. Works nicely.

files/en-us/web/css/reference/properties/text-decoration-inset/index.md

estelle · 2025-11-13T01:13:23Z

files/en-us/web/css/reference/properties/text-decoration-inset/index.md

+```css live-sample___auto-example
+u {
+  text-decoration-color: red;
+  text-decoration-thickness: 3px;


i would go with text-decoration: red 3px underline , but not required edit.

I'd rather not do this; I was kind of going for a subtle hint that the underline created on <u> is a text decoration. But at the same time, I didn't want to waffle on about that explicitly because it seemed out of scope for the article.

estelle · 2025-11-13T01:13:42Z

files/en-us/web/css/reference/properties/text-decoration-inset/index.md

+We define two groups of side-by-side {{htmlelement("u")}} elements:
+
+```html live-sample___auto-example
+<p id="one"><u>石井</u><u>艾俐俐</u></p>


should we add the lang attribute?

Yeah, I think that's probably a good idea. Added.

estelle · 2025-11-13T01:15:27Z

files/en-us/web/css/reference/properties/text-decoration-inset/index.md

+
+{{embedlivesample("auto-example", "100%", "200")}}
+
+Note how the `auto` value creates a gap in the underlines, whereas the `0` value results in no gap.


Suggested change

Note how the `auto` value creates a gap in the underlines, whereas the `0` value results in no gap.

Note how the `auto` value insets the text decoration, creating a gap in the underline between the two elements (but adding no space between the two elements), whereas the `0` value results in no gap.

it insets on both sides, which is subtle, so may not be noticed if not pointed out, so suggest explicitly pointing it out. Also, the "gap" is in the underlines but not in the text, so want to point that out too. My suggestion may not be the best verbiage, but i think it is important to point out.

It's not between two elements, but rather the underscore shortens at both ends, creating the appearance of a gap.

I believe it's important to explicitly clarify the rendering method here, as it's otherwise prone to misunderstanding. Before this property existed, Chinese developers would create gaps using u+u { margin-left: .125em;}. but it's not the same as text-decoration-inset.

Additionally, the approach in this article that uses border-image to simulate text-decoration-inset can be considered a polyfill. Could you look into adding it to this documentation?

https://chaoli.club/index.php/7000

Good call. I played with the text a bit and ended up updating it to:

Note how the auto value insets the text decoration subtly on both sides, creating a gap in between the underlines of the two elements (no space is added between the two elements themselves). The 0 value results in no gap.

It's not between two elements, but rather the underscore shortens at both ends, creating the appearance of a gap.

@yisibl OK, thanks for the clarification. In light of your comment, I've improved the auto value description on the page further.

In terms of adding polyfill/previous technique information, I'm not sure about this — this is not something we generally do on MDN, at least not these days. Polyfills change and go out of date, and adding previous technique information would also create a huge maintenance burden. So, I'm going to leave this information out.

estelle · 2025-11-13T01:22:44Z

files/en-us/web/css/reference/properties/text-decoration-inset/index.md

+
+A single `<length>` value will set the inset (if positive) or outset (if negative) on the start and end positions of the text decoration. To set the start and end positions separately, you can use two `<length>` values — the first one applies to the start position of the text decoration and the second one applies to the end.
+
+The `text-decoration-inset` property can also take the `auto` keyword, which causes the browser to choose a value to ensure that, if two decorated text boxes appear side-by-side, a gap is created between them so they do not appear to have a single text decoration. The `auto` value is particularly important when rendering Chinese text, as underlining is used to [punctuate proper nouns](https://www.w3.org/TR/clreq/#id88), and adjacent proper nouns should have separate underlines. See [Effect of the `auto` value](/en-US/docs/Web/CSS/Reference/Properties/text-decoration-inset#effect_of_the_auto_value) for an example.


Suggested change

The `text-decoration-inset` property can also take the `auto` keyword, which causes the browser to choose a value to ensure that, if two decorated text boxes appear side-by-side, a gap is created between them so they do not appear to have a single text decoration. The `auto` value is particularly important when rendering Chinese text, as underlining is used to [punctuate proper nouns](https://www.w3.org/TR/clreq/#id88), and adjacent proper nouns should have separate underlines. See [Effect of the `auto` value](/en-US/docs/Web/CSS/Reference/Properties/text-decoration-inset#effect_of_the_auto_value) for an example.

The `text-decoration-inset` property can also take the `auto` keyword, which causes the browser to inset the start and end positions ensuring that, if two decorated text boxes appear side-by-side, a gap is created between them so they do not appear to have a single text decoration. The `auto` value is particularly important when rendering Chinese text, as underlining is used to [punctuate proper nouns](https://www.w3.org/TR/clreq/#id88), and adjacent proper nouns should have separate underlines. See [Effect of the `auto` value](/en-US/docs/Web/CSS/Reference/Properties/text-decoration-inset#effect_of_the_auto_value) for an example.

Again, good to make this clear. In my next commit, I've added a variation of this, but also made a few other tweaks to the paragraph.

…/index.md Co-authored-by: Estelle Weyl <[email protected]>

pepelsbey

Looks good! Just a small nit below

pepelsbey · 2025-11-16T05:32:33Z

files/en-us/web/css/reference/properties/text-decoration-inset/index.md

+
+The `auto` value does not have the same effect as the initial value `0`. Setting `text-decoration-inset` to `0` causes there to be no space between decorations.
+
+The `text-decoration-inset` property is not inherited, and it is not a constituent property of the {{cssxref("text-decoration")}} shorthand.


I would suggest saying it a little simpler.

Suggested change

The `text-decoration-inset` property is not inherited, and it is not a constituent property of the {{cssxref("text-decoration")}} shorthand.

The `text-decoration-inset` property is not inherited, and it is not a part of the {{cssxref("text-decoration")}} shorthand.

I'm not sure I agree with this. My text is precise, and we do use this term commonly around the CSS section of CSS.

estelle

LGTM

* Add docs for the CSS text-decoration-inset property * Add extra information on Chinese punctuation * Update files/en-us/web/css/reference/properties/text-decoration-inset/index.md Co-authored-by: Estelle Weyl <[email protected]> * Update files/en-us/web/css/reference/properties/text-decoration-inset/index.md Co-authored-by: Estelle Weyl <[email protected]> * Update files/en-us/web/css/reference/properties/text-decoration-inset/index.md Co-authored-by: Estelle Weyl <[email protected]> * Fixes for estelle review comments plus other tweaks * improve auto description further --------- Co-authored-by: Estelle Weyl <[email protected]>

Add docs for the CSS text-decoration-inset property

98bd466

chrisdavidmills requested a review from a team as a code owner November 11, 2025 12:41

chrisdavidmills requested review from estelle and removed request for a team November 11, 2025 12:41

github-actions bot added Content:CSS Cascading Style Sheets docs size/m [PR only] 51-500 LoC changed labels Nov 11, 2025

chrisdavidmills mentioned this pull request Nov 11, 2025

[CSS] Rename text-decoration-trim to text-decoration-inset #41876

Open

8 tasks

chrisdavidmills requested a review from pepelsbey November 11, 2025 12:42

yisibl reviewed Nov 12, 2025

View reviewed changes

files/en-us/web/css/reference/properties/text-decoration-inset/index.md Outdated Show resolved Hide resolved

Add extra information on Chinese punctuation

64b3ea2

estelle reviewed Nov 13, 2025

View reviewed changes

chrisdavidmills and others added 5 commits November 13, 2025 08:41

Update files/en-us/web/css/reference/properties/text-decoration-inset…

1f280d1

…/index.md Co-authored-by: Estelle Weyl <[email protected]>

Update files/en-us/web/css/reference/properties/text-decoration-inset…

c2f1a9f

…/index.md Co-authored-by: Estelle Weyl <[email protected]>

Update files/en-us/web/css/reference/properties/text-decoration-inset…

03bbef1

…/index.md Co-authored-by: Estelle Weyl <[email protected]>

Fixes for estelle review comments plus other tweaks

f52795a

improve auto description further

414c86a

chrisdavidmills requested review from estelle and yisibl November 13, 2025 10:05

pepelsbey approved these changes Nov 16, 2025

View reviewed changes

estelle approved these changes Nov 16, 2025

View reviewed changes

chrisdavidmills merged commit c5c7486 into mdn:main Nov 17, 2025
8 checks passed

chrisdavidmills deleted the text-decoration-inset branch November 17, 2025 09:15


		## Description

		The `text-decoration-inset` property allows you to adjust the start and/or end points of a text container's text decoration, as set by the {{cssxref("text-decoration")}} shorthand and associated longhand properties. This is useful for creating effects where you want the text decoration to be inset or outset from the text itself, or shifted in position. See [Basic use cases](/en-US/docs/Web/CSS/Reference/Properties/text-decoration-inset#basic_use_cases) for an example of each.


		The `text-decoration-inset` property can also take the `auto` keyword, which causes the browser to choose a value to ensure that, if two decorated text boxes appear side-by-side, a gap is created between them so they do not appear to have a single text decoration. The `auto` value is particularly important when rendering Chinese text, as underlining is used to [punctuate proper nouns](https://www.w3.org/TR/clreq/#id88), and adjacent proper nouns should have separate underlines. See [Effect of the `auto` value](/en-US/docs/Web/CSS/Reference/Properties/text-decoration-inset#effect_of_the_auto_value) for an example.

		The `auto` value does not have the same effect as a `text-decoration-inset` value of `0` (which is the initial value) — `0` causes there to be no space between decorations.


		{{embedlivesample("auto-example", "100%", "200")}}

		Note how the `auto` value creates a gap in the underlines, whereas the `0` value results in no gap.

	Note how the `auto` value creates a gap in the underlines, whereas the `0` value results in no gap.
	Note how the `auto` value insets the text decoration, creating a gap in the underline between the two elements (but adding no space between the two elements), whereas the `0` value results in no gap.


		A single `<length>` value will set the inset (if positive) or outset (if negative) on the start and end positions of the text decoration. To set the start and end positions separately, you can use two `<length>` values — the first one applies to the start position of the text decoration and the second one applies to the end.

		The `text-decoration-inset` property can also take the `auto` keyword, which causes the browser to choose a value to ensure that, if two decorated text boxes appear side-by-side, a gap is created between them so they do not appear to have a single text decoration. The `auto` value is particularly important when rendering Chinese text, as underlining is used to [punctuate proper nouns](https://www.w3.org/TR/clreq/#id88), and adjacent proper nouns should have separate underlines. See [Effect of the `auto` value](/en-US/docs/Web/CSS/Reference/Properties/text-decoration-inset#effect_of_the_auto_value) for an example.


		The `auto` value does not have the same effect as the initial value `0`. Setting `text-decoration-inset` to `0` causes there to be no space between decorations.

		The `text-decoration-inset` property is not inherited, and it is not a constituent property of the {{cssxref("text-decoration")}} shorthand.

Add docs for the CSS text-decoration-inset property #41901

Add docs for the CSS text-decoration-inset property #41901

Uh oh!

Conversation

chrisdavidmills commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

github-actions bot commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

estelle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yisibl Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pepelsbey left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

estelle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

chrisdavidmills commented Nov 11, 2025 •

edited

Loading

github-actions bot commented Nov 11, 2025 •

edited

Loading

yisibl Nov 13, 2025 •

edited

Loading