Skip to content

Commit 9d1eab3

Browse files
chrisdavidmillsestelle
chrisdavidmills
and
estelle
committed
Add docs for the CSS text-decoration-inset property (#41901)
* 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]>
1 parent 066163b commit 9d1eab3

File tree

2 files changed

+240
-1
lines changed
  • files/en-us/web/css
    • guides/text_decoration
    • reference/properties/text-decoration-inset

2 files changed

+240
-1
lines changed

‎files/en-us/web/css/guides/text_decoration/index.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ p {
7777

7878
- {{cssxref("text-decoration")}}
7979
- {{cssxref("text-decoration-color")}}
80+
- {{cssxref("text-decoration-inset")}}
8081
- {{cssxref("text-decoration-line")}}
8182
- {{cssxref("text-decoration-skip")}}
8283
- {{cssxref("text-decoration-skip-ink")}}
@@ -90,7 +91,7 @@ p {
9091
- {{cssxref("text-underline-offset")}}
9192
- {{cssxref("text-underline-position")}}
9293

93-
The specification also defines the `text-decoration-skip-box`, `text-decoration-skip-self`, `text-decoration-skip-spaces`, `text-decoration-trim`, and `text-emphasis-skip` properties, which are not yet supported by any browser.
94+
The specification also defines the `text-decoration-skip-box`, `text-decoration-skip-self`, `text-decoration-skip-spaces`, and `text-emphasis-skip` properties, which are not yet supported by any browser.
9495

9596
## Guides
9697

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

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
---
2+
title: text-decoration-inset
3+
slug: Web/CSS/Reference/Properties/text-decoration-inset
4+
page-type: css-property
5+
browser-compat: css.properties.text-decoration-inset
6+
sidebar: cssref
7+
---
8+
9+
The **`text-decoration-inset`** [CSS](/en-US/docs/Web/CSS) property enables adjusting the start and end points of an element's text decoration so it can be shortened, lengthened, or have its position shifted with respect to the rendered text.
10+
11+
{{InteractiveExample("CSS Demo: text-decoration-inset")}}
12+
13+
```css interactive-example-choice
14+
text-decoration-inset: 20px;
15+
```
16+
17+
```css interactive-example-choice
18+
text-decoration-inset: -0.5em;
19+
```
20+
21+
```css interactive-example-choice
22+
text-decoration-inset: 20px 1em;
23+
```
24+
25+
```css interactive-example-choice
26+
text-decoration-inset: -0.5rem -1.5rem;
27+
```
28+
29+
```css interactive-example-choice
30+
text-decoration-inset: -2ex 10vw;
31+
```
32+
33+
```html interactive-example
34+
<section id="default-example">
35+
<p id="example-element">Karmadrome</p>
36+
</section>
37+
```
38+
39+
```css interactive-example
40+
#example-element {
41+
font: 2.5em sans-serif;
42+
text-decoration: underline 0.3em limegreen;
43+
}
44+
```
45+
46+
## Syntax
47+
48+
```css
49+
/* auto keyword */
50+
text-decoration-inset: auto;
51+
52+
/* One <length> value */
53+
text-decoration-inset: 20px;
54+
text-decoration-inset: -2rem;
55+
56+
/* Two <length> values */
57+
text-decoration-inset: 20px 1em;
58+
text-decoration-inset: -0.5rem -1.5rem;
59+
text-decoration-inset: -2ex 1vw;
60+
61+
/* Global values */
62+
text-decoration-inset: inherit;
63+
text-decoration-inset: initial;
64+
text-decoration-inset: revert;
65+
text-decoration-inset: revert-layer;
66+
text-decoration-inset: unset;
67+
```
68+
69+
### Values
70+
71+
One or two {{cssxref("&lt;length>")}} values, or the keyword `auto`.
72+
73+
- {{cssxref("&lt;length>")}}
74+
- : Specifies the amount to adjust the text decoration position by. Positive values inset the text decoration (make it shorter) while negative values outset the text decoration (make it longer). If one value is specified, it applies to both the text decoration start and end points. If two values are specified, the first one applies to the text decoration start point and the second one applies to the text decoration end point.
75+
- `auto`
76+
- : The browser chooses a start and end inset amount to ensure that, if two decorated text boxes appear side-by-side, the appearence of a gap is created between their text decorations so they do not appear to have a single text decoration.
77+
78+
## Description
79+
80+
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.
81+
82+
The `text-decoration-inset` property allows you to adjust the start and/or end points of a text container's text decoration. 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.
83+
84+
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.
85+
86+
The `text-decoration-inset` property can also take the `auto` keyword. This causes the browser to inset the text decoration start and end points to ensure that, if two decorated text boxes appear side-by-side, they do not appear to have a single text decoration. The `auto` value is particularly important when rendering Chinese text, where 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.
87+
88+
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.
89+
90+
The `text-decoration-inset` property is not inherited, and it is not a constituent property of the {{cssxref("text-decoration")}} shorthand.
91+
92+
## Formal definition
93+
94+
{{CSSInfo}}
95+
96+
## Formal syntax
97+
98+
{{csssyntax}}
99+
100+
## Examples
101+
102+
### Basic use cases
103+
104+
In this example, we demonstrate the outset, inset, and "shifted" use cases.
105+
106+
#### HTML
107+
108+
We define an unordered list with three list items, each with a separate `id`.
109+
110+
```html live-sample___use-case-examples
111+
<ul>
112+
<li id="one">Outset decoration</li>
113+
<li id="two">Inset decoration</li>
114+
<li id="three">Shifted decoration</li>
115+
</ul>
116+
```
117+
118+
#### CSS
119+
120+
We give each list item a different {{cssxref("text-decoration")}} and `text-decoration-inset`:
121+
122+
- The first one has a thick lime green underline, which is outset equally by `10px` on both sides.
123+
- The second one has a medium thickness white strike-through, which is inset equally by `0.5em` on both sides.
124+
- The third one has a thin wavy blue underline, which is moved to the right by `1em`.
125+
126+
```css hidden live-sample___use-case-examples
127+
li {
128+
font-family: sans-serif;
129+
font-size: 2em;
130+
margin-bottom: 20px;
131+
}
132+
133+
@supports not (text-decoration-inset: auto) {
134+
body::before {
135+
content: "Your browser doesn't support the text-decoration-inset property.";
136+
background-color: wheat;
137+
display: block;
138+
padding: 10px 0;
139+
width: 100%;
140+
text-align: center;
141+
}
142+
}
143+
```
144+
145+
```css live-sample___use-case-examples
146+
#one {
147+
text-decoration: underline 0.3em limegreen;
148+
text-decoration-inset: -10px;
149+
}
150+
151+
#two {
152+
text-decoration: line-through 5px white;
153+
text-decoration-inset: 0.5em;
154+
}
155+
156+
#three {
157+
text-decoration: underline wavy 2px blue;
158+
text-decoration-inset: 1em -1em;
159+
}
160+
```
161+
162+
#### Result
163+
164+
This renders like so:
165+
166+
{{embedlivesample("use-case-examples", "100%", "230")}}
167+
168+
### Effect of the `auto` value
169+
170+
This example demonstrates the effect of the `text-decoration-inset: auto` value.
171+
172+
#### HTML
173+
174+
We define two groups of side-by-side {{htmlelement("u")}} elements:
175+
176+
```html live-sample___auto-example
177+
<p lang="zh" id="one"><u>石井</u><u>艾俐俐</u></p>
178+
179+
<p lang="zh" id="two"><u>石井</u><u>艾俐俐</u></p>
180+
```
181+
182+
#### CSS
183+
184+
Each `<u>` element has a `red` color and `3px` thickness set on its underline. The first group of `<u>` elements has a `text-decoration-inset` value of `auto` set on them, while the second set has the initial `text-decoration-inset` value of `0` explicitly set on them, for comparison purposes:
185+
186+
```css hidden live-sample___auto-example
187+
u {
188+
font-family: sans-serif;
189+
font-size: 2em;
190+
}
191+
192+
@supports not (text-decoration-inset: auto) {
193+
body::before {
194+
content: "Your browser doesn't support the text-decoration-inset property.";
195+
background-color: wheat;
196+
display: block;
197+
padding: 10px 0;
198+
width: 100%;
199+
text-align: center;
200+
}
201+
}
202+
```
203+
204+
```css live-sample___auto-example
205+
u {
206+
text-decoration-color: red;
207+
text-decoration-thickness: 3px;
208+
}
209+
210+
#one u {
211+
text-decoration-inset: auto;
212+
}
213+
214+
#two u {
215+
text-decoration-inset: 0;
216+
}
217+
```
218+
219+
#### Result
220+
221+
This renders like so:
222+
223+
{{embedlivesample("auto-example", "100%", "200")}}
224+
225+
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.
226+
227+
## Specifications
228+
229+
{{Specifications}}
230+
231+
## Browser compatibility
232+
233+
{{Compat}}
234+
235+
## See also
236+
237+
- {{cssxref("text-decoration")}}
238+
- The [CSS text decoration](/en-US/docs/Web/CSS/Guides/Text_decoration) module

0 commit comments

Comments
 (0)