In CSS1 and CSS2, the ‘text-decoration’ property controls text decorations: underline, overline, line-through, and blinking. CSS2 adds text shadows, which the ‘text-shadow’ property controls. However, the ‘text-decoration’ property has limitations stemming from its syntax, precluding fine control over each of those formatting effects. Specifically, it offers no way to control the color or line style of the underline, overline or line-through.
CSS3 extends the model by introducing new properties allowing additional controls over those formatting effects. CSS3 also makes turning these formatting effects on or off possible without affecting any other ‘text-decoration’ settings.
Furthermore, to reflect the usage of underline in East Asian vertical writing, a new control is offered for the underline positioning; this allows the underline to appear before (on the right in vertical text flow) or after (on the left in vertical text flow) the formatted text. The property is called ‘text-underline-position’.
The ‘text-decoration’ property itself is now a shorthand property for all these new properties. However, the ‘text-decoration’ values are not composites built from the values of constituent properties. Rather, ‘text-decoration’ values come from a small set specific to the ‘text-decoration’ shorthand property.
These properties describe decorations that are added to the text of an element. If they are specified for a block-level element, they affect the root inline box (the anonymous inline box which wraps all the inline children of an element).
If they are specified for (or affects) an inline-level element, they affect all boxes generated by the element. If an element contains no text (ignoring white space in elements that have ‘all-space-treatment’ set to ‘collapse’), user agents MUST refrain from rendering text decorations on the element. For example, elements containing only images and white space will not be underlined .
Text decoration properties are not inherited, but descendant boxes MUST be formatted with the same decoration (e.g., they must all be underlined). The color of decorations MUST remain the same even if descendant elements have different ‘color’ values.
When a text decoration could result in text being unintentionally overdrawn by the text decoration style, the user agents MAY chose to skip the text decoration over the intersecting area by using ‘text-underline-mode’, ‘text-line-through-mode’ or ‘text-overline-mode’ with the appropriate values.
In determining the position of and thickness of text decoration lines, user agents MAY consider the font sizes of and dominant baselines of children. Of course, user agents MAY ignore children in these determinations. Such an averaging is done on a line per line basis.
Various text decoration styles are
| Value | Text Decoration |
| Names: | text-underline-style, text-line-through-style, text-overline-style |
| Value: | none | solid | double | dotted | dashed | dot-dash | dot-dot-dash | wave |
| Initial: | none |
| Applies to: | all elements with and generated content with textual content |
| Inherited: | no |
| Percentages: | N/A |
| Media: | visual |
| Computed value: | specified value (except for initial and inherit) |
These properties specify the line style for underline, line-through and overline text decoration. Possible values are
- none – Produces no line.
- solid – Produces a solid line.
- double – Produces a double line.
- dotted – Produces a dotted line.
- dashed – Produces a dashed line style.
- dot-dash – Produces a line whose repeating pattern is a dot followed by a dash.
- dot-dot-dash – Produces a line whose repeating pattern is two dots followed by a dash.
- wave – Produces a wavy line.
Text Decoration Width
These property specifies the line width for the underline, line-through and overline text decorations. Possible values:
- auto – The user agent may use any algorithm to determine the text decoration width. Implementers are encouraged to consider the font-sizes and baselines of all affected text. The text decoration style should affect the resulting value (the style ‘double’, for instance, would produce a width greater than the style ‘solid’ produces). The computed value is ‘auto’.
- normal – The text decoration width is the normal text decoration width for the nominal font. If no font characteristic exists for the width of the text decoration in question, the user agent should proceed as though ‘auto’ were specified. The computed value is ‘normal’.
- <number> – The text decoration width is the product of the <number> and the computed ‘font-size’. The computed value is ‘<number>’.
- <length> – The text decoration width is the length. The computed value is the corresponding absolute <length>.
- <percentage> – The text decoration width is the product of the <percentage> and the computed ‘font-size’. The computed value is the absolute <length>.
- thin – This value is equivalent to a <number> value kept by the user agent. The <number> MUST be constant through a given view of a document and SHOULD yield a thin line. The computed value is ‘thin’.
- medium – This value is equivalent to a <number> value kept by the user agent. The <number> MUST be constant through a given view of a document, MUST be greater than or equal to the ‘thin’ number and SHOULD yield a medium line.
- thick – This value is equivalent to a <number> value kept by the user agent. The <number> MUST be constant through a given view of a document, MUST be greater than or equal to the ‘medium’ number and SHOULD yield a thick line.
Text Decoration Color
These property specifies the line colors for the underline, line-through and overline text decorations. Possible values:
- <color> – Specifies a color value.
Text Decoration Mode
These properties set the mode for the underline, line-through and overline text decorations, determining whether the text decoration affects the space characters or not. ‘Space characters’ are all characters classified by the Unicode Standard [UNICODE] as category ‘Zs’, in addition to the white space characters. Possible values:
- continuous – This value means that the line is continuous.
- skip-white-space – This means that space characters will not be lined.
Text Shadows
<shadow> itself is defined as “[<color> <length> <length> <length>? | <length> <length> <length>? <color>?]”.
This property accepts a comma-separated list of shadow effects to be applied to the text of the element. The shadow effects are applied in the order specified and may thus overlay each other, but they will never overlay the text itself. Shadow effects do not alter the size of a box, but may extend beyond its boundaries. The stack level of the shadow effects is the same as for the element itself.
Each shadow effect MUST specify a shadow offset and MAY optionally specify a blur radius and a shadow color.
A shadow offset is specified with two <length> terms that indicate the distance from the text. The first length term specifies the horizontal distance to the right of the text. A negative horizontal length term places the shadow to the left of the text. The second length term specifies the vertical distance below the text. A negative vertical length term places the shadow above the text.
A blur radius MAY be specified after the shadow offset. The blur radius is a length value that indicates the boundaries of the blur effect. The exact algorithm for computing the blur effect is not specified. If no blur radius is specified, the treatment is as if a blur radius of zero were specified and the shadow has the same size and shape as the glyphs that cast it. User agents MAY only implement only part of this property by ignoring blur effects. Such user agents should consider declarations that specify the blur radius to be parser errors, as described in the Syntax module [link TBD].
A color term may be specified before or after the length terms of the shadow effect. The color term will be used as the basis for the shadow effect. If no color is specified, the value of the ‘color’ property will be used instead.
Text shadows may be used with the ::first-letter and ::first-line pseudo-elements.
