<pre class='metadata'>

Title: CSS Pseudo-Elements Module Level 4

Shortname: css-pseudo

Level: 4

Status: ED

Work Status: Refining

Group: csswg

ED: https://drafts.csswg.org/css-pseudo-4/

TR: https://www.w3.org/TR/css-pseudo-4/

Previous Version: https://www.w3.org/TR/2020/WD-css-pseudo-4-20201231/

Previous Version: https://www.w3.org/TR/2019/WD-css-pseudo-4-20190225/

Previous Version: https://www.w3.org/TR/2016/WD-css-pseudo-4-20160607/

Previous Version: https://www.w3.org/TR/2015/WD-css-pseudo-4-20150115/

!Issues List: <a href="https://drafts.csswg.org/css-pseudo/#issues-index">Tracked in Editor's Draft</a>

Editor: Daniel Glazman, Disruptive Innovations, w3cid 13329

Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400

Editor: Alan Stearns, Adobe Systems Inc., stearns@adobe.com, w3cid 46659

Abstract: This CSS module defines pseudo-elements, abstract elements that represent portions of the CSS render tree that can be selected and styled.

At Risk: the ''::prefix'' and ''::postfix'' sub-elements of ''::first-letter''

Ignored Terms: initial-letter, PseudoElement, pseudo(), selectors

Default Highlight: css

Indent: 2

</pre>

<pre class="link-defaults">

spec:css-color-4; type:value; text:currentcolor

spec:css-color-4; type:property; text:color

spec:fill-stroke-3; type:property; text:stroke-width

</pre>

<h2 id="intro">Introduction</h2>

<em>This section is informative.</em>

<a>Pseudo-elements</a> represent abstract elements of the document

beyond those elements explicitly created by the document language.

Since they are not restricted to fitting into the document tree,

they can be used to select and style portions of the document

that do not necessarily map to the document's tree structure.

For instance, the ''::first-line'' pseudo-element can

select content on the first formatted line of an element

<em>after</em> text wrapping,

allowing just that line to be styled differently

from the rest of the paragraph.

Each pseudo-element is associated with an <a>originating element</a>

and has syntax of the form ''::name-of-pseudo''.

This module defines the pseudo-elements that exist in CSS

and how they can be styled.

For more information on pseudo-elements in general,

and on their syntax and interaction with other <a>selectors</a>,

see [[!SELECTORS-4]].

<h2 id="typographic-pseudos">

Typographic Pseudo-elements</h2>

<h3 id="first-line-pseudo">

First-Line Text: the ''::first-line'' pseudo-element</h3>

The <dfn>::first-line</dfn> [=pseudo-element=] represents

the contents of the [=first formatted line=]

of its [=originating element=].

<div class="example">

The rule below means

“change the letters of the first line of every <code>p</code> element to uppercase”:

<pre class="lang-css">p::first-line { text-transform: uppercase }</pre>

The selector ''p::first-line''

does not match any real document element.

It instead matches a pseudo-element

that the user agent will automatically insert

at the beginning of every <code>p</code> element.

</div>

Note: Note that the length of the first line depends on a number of factors,

including the width of the page, the font size, etc.

<div class="example" id="first-line-example">

For example, given an ordinary HTML [[HTML5]] paragraph such as:

<pre class="lang-markup">

&lt;P&gt;This is a somewhat long HTML paragraph

that will be broken into several lines.

The first line will be styled

by the ‘::first-line’ pseudo-element.

The other lines will be treated

as ordinary lines in the paragraph.&lt;/P&gt;

</pre>

Depending on the width of the element,

its lines might be broken as follows:

<pre class="figure">

THIS IS A SOMEWHAT LONG HTML PARAGRAPH THAT

will be broken into several lines. The first

line will be styled by the ‘::first-line’

pseudo-element. The other lines will be

treated as ordinary lines in the paragraph.

</pre>

or alternately as follows:

<pre class="figure">

THIS IS A SOMEWHAT LONG

HTML paragraph that will

be broken into several

lines. The first line will

be styled by the

‘::first-line’ pseudo-

element. The other lines

will be treated as ordinary

lines in the paragraph.

</pre>

</div>

<h4 id="first-text-line">

Finding the First Formatted Line</h4>

In CSS, the ''::first-line'' pseudo-element

can only have an effect when attached to a <a>block container</a>:

* The <dfn export>first formatted line</dfn> of

a [=block container=] that establishes an [=inline formatting context=]

represents the [=inline-level=] content of its first [=line box=].

* The [=first formatted line=] of

a [=block container=] or [=multi-column container=]

that contains [=block-level=] content

(and is not a [=table wrapper box=])

is the [=first formatted line=] of

its first [=in-flow=] [=block-level=] child.

If no such line exists,

it has no [=first formatted line=].

Note: The [=first formatted line=] can be an empty line.

For example, the first line of the <code>p</code> in

<code class="lang-markup">&lt;p&gt;&lt;br&gt;First&hellip;</code>

doesn't contain any letters.

Thus the word “First” is not on the first formatted line,

and will not be affected by ''p::first-line''.

Note: The first line of a [=block container=]

that does not itself participate in a [=block formatting context=]

cannot be the first formatted line of an ancestor element.

Thus, in <code class="lang-markup">&lt;DIV&gt;&lt;P STYLE="display: inline-block"&gt;Hello&lt;BR&gt;Goodbye&lt;/P&gt; etcetera&lt;/DIV&gt;</code>

the first formatted line of the <code>DIV</code> is not the line “Hello”,

but rather the line that contains that entire inline block.

When a [=first formatted line=] is represented

by multiple ''::first-line'' pseudo-elements,

they are nested in the same order as their [=originating elements=].

The [=inline-level=] contents of this line--

including its [=root inline box=] fragment--

are nested within the innermost ''::first-line'' [=pseudo-element=].

<div class="example">

Consider the following markup:

<pre class="lang-markup">

&lt;DIV&gt;

&lt;P&gt;First paragraph&lt;/P&gt;

&lt;P&gt;Second paragraph&lt;/P&gt;

&lt;/DIV&gt;

</pre>

If we assume a [=fictional tag sequence=] to represent

the elements’ ''::first-line'' pseudo elements,

it would be something like:

<pre class="lang-markup">

&lt;DIV&gt;

&lt;P&gt;&lt;DIV::first-line&gt;&lt;P::first-line&gt;First paragraph&lt;/P::first-line&gt;&lt;/DIV::first-line&gt;&lt;/P&gt;

&lt;P&gt;&lt;P::first-line&gt;Second paragraph&lt;/P::first-line&gt;&lt;/P&gt;

&lt;/DIV&gt;

</pre>

</div>

<h4 id="first-line-styling">

Styling the ''::first-line'' Pseudo-element</h4>

The ''::first-line'' pseudo-element’s generated box

behaves similar to that of an [=inline-level box=], but with certain restrictions.

The following CSS properties apply to a ''::first-line'' pseudo-element:

<ul>

<li>all font properties (see [[CSS-FONTS-4]])

<li>the 'color' and 'opacity' properties (see [[CSS-COLOR-4]])

<li>all background properties (see [[CSS-BACKGROUNDS-4]])

<li>any typesetting properties that apply to inline elements (see [[CSS-TEXT-3]])

<li>all text decoration properties (see [[CSS-TEXT-DECOR-3]])

<li>the 'ruby-position' property (see [[CSS-RUBY-1]])

<li>any inline layout properties that apply to inline elements (see [[CSS-INLINE-3]])

<li>any other properties defined to apply to ''::first-line''

by their respective specifications

</ul>

User agents may apply other properties as well except for

the following excluded properties:

<ul>

<li>'writing-mode'

<li>'direction'

<li>'text-orientation'

</ul>

Note: Setting 'line-height' on ''::first-line'' inherits to

the fragment of the [=root inline box=]

that wraps the contents of the first line,

and therefore can both increase and decrease the height of the first line box.

<h4 id="first-line-inheritance">

Inheritance and the ''::first-line'' Pseudo-element</h4>

During CSS [=inheritance=],

the [=box fragment|fragment=] of a child that occurs on the first line

inherits any standard [=inherited properties=]--

except the properties excluded above--

from the ''::first-line'' pseudo-element.

For all other properties,

including all [=custom properties=] [[!CSS-VARIABLES-1]],

inheritance is

from the non-pseudo parent.

(The portion of a child element that does not occur on the first line

always inherits from the non-pseudo parent.)

<div class="example">

In the common case (of standard inherited CSS properties),

[=inheritance=] into and from a ''::first-line'' pseudo-element

can be understood by writing out a <dfn>fictional tag sequence</dfn>

to represent ''::first-line''.

Consider the <a href="#first-line-example">earlier example</a>;

in case of the first rendering, the fictional tag sequence would be:

<pre class="lang-markup">

&lt;P&gt;<strong>&lt;p::first-line></strong>This is a somewhat long HTML paragraph

that<strong>&lt;/p::first-line></strong> will be broken into several lines.

The first line will be styled

by the ‘::first-line’ pseudo-element.

The other lines will be treated

as ordinary lines in the paragraph.&lt;/p&gt;

</pre>

And in the case of the second rendering:

<pre class="lang-markup">

&lt;p&gt;<strong>&lt;p::first-line></strong>This is a somewhat long<strong>&lt;/p::first-line></strong> HTML paragraph

that will be broken into several lines.

The first line will be styled

by the ‘::first-line’ pseudo-element.

The other lines will be treated

as ordinary lines in the paragraph.&lt;/p&gt;

</pre>

</div>

<div class="example">

If a pseudo-element breaks up a real element,

the effect can often be described

by a <a>fictional tag sequence</a>

that closes and then re-opens the element.

Suppose we mark up the earlier example

with a <code>span</code> element encompassing the first sentence:

<pre class="lang-markup">

&lt;p&gt;<strong>&lt;span></strong>This is a somewhat long HTML paragraph

that will be broken into several lines.<strong>&lt;/span></strong>

The first line will be styled

by the ‘::first-line’ pseudo-element.

The other lines will be treated

as ordinary lines in the paragraph.&lt;/p&gt;

</pre>

The effect of the first rendering

would be similar to the following [=fictional tag sequence=]:

<pre class="lang-markup">

&lt;p&gt;<strong>&lt;p::first-line>&lt;span></strong>This is a somewhat long HTML paragraph

that<strong>&lt;/span>&lt;/p::first-line>&lt;span></strong> will be broken into several lines.<strong>&lt;/span></strong>

The first line will be styled

by the ‘::first-line’ pseudo-element.

The other lines will be treated

as ordinary lines in the paragraph.&lt;/p&gt;

</pre>

</div>

<h3 id="first-letter-pseudo">

First-Letter Text: ''::first-letter'' pseudo-element and its ''::prefix'' and ''::postfix'' children</h3>

<div class="figure">

<img alt="A drop-cap initial letter, including the opening quotation mark before it." src="images/first-letter2.gif">

</div>

The <dfn>::first-letter</dfn> [=pseudo-element=] represents

the first Letter, Number, or Symbol

(Unicode category <code>L*</code>, <code>N*</code>, or <code>S*</code>) [=typographic character unit=]

on the <a>first formatted line</a> of its <a>originating element</a>

(the <dfn>first letter</dfn>)

as well as its associated punctuation.

Collectively, this text is the <dfn>first-letter text</dfn>.

The ''::first-letter'' pseudo-element can be used

to create “initial caps” and “drop caps”,

which are common typographic effects.

<div class="example">

For example, the following rule creates a 2-line drop-letter

on every paragraph following a level-2 header,

using the 'initial-letter' property defined in [[CSS-INLINE-3]]:

<pre class="lang-css">h2 + p::first-letter { initial-letter: 3; }</pre>

</div>

Note: The [=first letter=] may in fact be a digit,

e.g., the “6” in “67 million dollars is a lot of money.”

To allow independent styling of the [=first letter=] itself

and its adjacent punctuation,

associated preceding punctuation

is represented by the <dfn for="::first-letter">::prefix</dfn>

[=sub-pseudo-element=] of the ''::first-letter'' [=pseudo-element=]

(''::first-letter::prefix'');

and associated following punctuation

is represented by the <dfn for="::first-letter">::postfix</dfn>

[=sub-pseudo-element=] of the ''::first-letter'' [=pseudo-element=]

(''::first-letter::postfix'').

See [[#first-letter-pattern]], below.

<h4 id="first-letter-pattern">

First Letters and Associated Punctuation</h4>

As explained in [[CSS-TEXT-3#characters]],

a <a>typographic character unit</a> can include more than one Unicode codepoint.

For example, combining characters must be kept with their base character.

Also, languages may have additional rules

about how to treat certain letter combinations.

In Dutch, for example, if the letter combination "ij" appears at the beginning of an element,

both letters should be considered within the ''::first-letter'' pseudo-element. [[UAX29]]

When selecting the [=first letter=],

the UA should tailor its definition of <a>typographic character unit</a>

to reflect the first-letter traditions of

the ''::first-letter'' pseudo-element’s <em>[=containing block=]</em>’s [=content language=].

Preceding and following punctuation

must also be included as part of the [=first-letter text=]

in the ''::first-letter'' pseudo-element

as follows:

<ul>

<li>

All punctuation--

i.e, characters that belong to the Punctuation (<code>P*</code>) <a>Unicode general category</a> [[!UAX44]]--

that precedes the [=first letter=].

<li>

Any punctuation other than opening punctuation and dashes--

i.e. characters that belong to the Punctuation (<code>P*</code>) <a>Unicode general category</a>,

excluding Open Punctuation (<code>Ps</code>)

and Dash Punctuation (<code>Pd</code>)--

that follows the [=first letter=].

<li>

Any intervening typographic space--

i.e. characters that belong to the <code>Zs</code> Unicode general category [[!UAX44]]

<em>other than</em>

U+3000 IDEOGRAPHIC SPACE or

any <a spec=css-text-3>word-separator characters</a>

</ul>

<div class="note">

Informally represented, the [=first-letter text=]’s pattern here

can be roughly

(ignoring the exclusion of word separators from <code>Zs</code>)

represented as

<code highlight="bnf" style="font-family: inherit">

(P (Zs|P)*)? (L\|N\|S) ((Zs|P−(Ps|Pd))* (P−(Ps|Pd))?</code>

or, alternatively,

<code highlight="bnf" style="font-family: inherit">

(&#91;P] [Zs P]*)? [L N S] ([Zs [P--[Ps Pd]]]* [P--[Ps Pd]])?</code>

<!-- this is not actually BNF, but it highlights better that way -->

<!-- Bikeshed is <a href="https://github.com/tabatkins/bikeshed/issues/2202">eating punctuation</a> in this note (unless escaped with undocumented escape sequences), which is not helpful. -->

<pre class=railroad>

Optional:

Sequence:

N: P

ZeroOrMore:

Choice:

N: P

N: Zs

Choice:

N: L

N: N

N: S

Optional:

Sequence:

N: P − (Ps ∪ Pd)

ZeroOrMore:

Choice:

N: P − (Ps ∪ Pd)

N: Zs

</pre>

</div>

See [[css-text-3#characters]] and [[css-text-3#character-properties]]

for more information on [=typographic character units=]

and their Unicode properties.

[[!CSS-TEXT-3]]

<h4 id="first-letter-application">

Finding the First-Letter Text</h4>

As with ''::first-line'',

the ''::first-letter'' pseudo-element

can only have an effect when attached to a [=block container=].

Its [=first-letter text=] is the first such [=inline-level content=]

participating in the [=inline formatting context=]

of its [=originating element=]’s [=first formatted line=],

if it is not preceded by any other in-flow content

(such as images or inline tables) on its line.

For this purpose, any [=marker boxes=] are ignored,

as if they were out-of-flow.

However, if an element has in-flow ''::before'' or ''::after'' content,

the [=first-letter text=] is selected from the content of the element

<em>including</em> that generated content.

<div class="example">

Example:

After the rule <code class="lang-css">p::before {content: "Note: "}</code>, the

selector ''p::first-letter'' matches the "N" of "Note".

</div>

If no qualifying text exists,

then there is no [=first-letter text=]

and no ''::first-letter'' pseudo-element.

Note: When the [=first formatted line=] is empty,

''::first-letter'' will not match anything.

For example, in this HTML fragment:

<code class="lang-markup">&lt;p&gt;&lt;br&gt;First...</code>

the first line doesn't contain any letters,

so ''::first-letter'' doesn't match anything.

In particular, it does not match the “F” of “First”,

which is on the second line.

Note: As with ''::first-line'',

the [=first-letter text=] of a [=block container=]

that does not participate in a [=block formatting context=]

cannot be the [=first-letter text=] of an ancestor element.

Thus, in <code class="lang-markup">&lt;DIV&gt;&lt;P STYLE="display: inline-block"&gt;Hello&lt;BR&gt;Goodbye&lt;/P&gt; etcetera&lt;/DIV&gt;</code>

the [=first letter=] of the <code>DIV</code> is not the letter “H”.

In fact, the <code>DIV</code> doesn't have a [=first letter=].

Any portion of the [=first-letter text=]

that is wrapped to the next line

no longer forms part of the ''::first-letter'' [=pseudo-element=].

<h4 id="first-letter-tree">

Inheritance and Box Tree Structure of the First-Letter Pseudo-elements</h4>

The ''::first-letter'' pseudo-element is wrapped

immediately around the [=first-letter text=] it represents,

even if that text is in a descendant.

When a [=first-letter text=] is represented by multiple ''::first-letter'' pseudo-elements,

they are nested in the same order as their [=originating elements=].

[=Inheritance=] behaves accordingly.

<div class="example">

Consider the following markup:

<pre class="lang-markup">

&lt;div&gt;

&lt;p&gt;&lt;span&gt;The first few words&lt;/span>

and the rest of the paragraph.

&lt;/div&gt;

</pre>

If we assume a [=fictional tag sequence=]

to represent the elements’ ''::first-letter'' pseudo-elements,

it would be something like:

<pre>

&lt;div&gt;

&lt;p&gt;&lt;span&gt;<strong>&lt;div::first-letter&gt;&lt;p::first-letter&gt;</strong>T<strong>&lt;/&hellip;&gt;&lt;/&hellip;&gt;</strong>he first few words&lt;/span>

and the rest of the paragraph.

&lt;/div&gt;

</pre>

</div>

If any ''::first-letter::prefix'' or ''::first-letter::postfix'' [=pseudo-elements=] exist,

they are nested within the innermost ''::first-letter'',

and otherwise interpreted similar to ''::first-letter'' itself.

<div class="example">

Consider the following markup:

<pre class="lang-markup">

&lt;div&gt;

&lt;p&gt;&lt;span&gt;“The first few words&lt;/span>

and the rest of the quotation.

&lt;/div&gt;

</pre>

If we assume a [=fictional tag sequence=]

to represent the elements’ ''::first-letter'' pseudo-elements,

it would be something like:

<pre>

&lt;div&gt;

&lt;p&gt;&lt;span&gt;&lt;div::first-letter&gt;&lt;p::first-letter&gt;<strong>&lt;div::first-letter::prefix&gt;&lt;p::first-letter::prefix&gt;</strong>“<strong>&lt;/&hellip;&gt;&lt;/&hellip;&gt;</strong>T&lt;/&hellip;&gt;&lt;/&hellip;&gt;he first few words&lt;/span>

and the rest of the paragraph.

&lt;/div&gt;

</pre>

</div>

If the characters that would form the [=first-letter text=]

are not all in the same element

(as the <code>‘T</code> in <code class="lang-css">&lt;p&gt;‘&lt;em&gt;T...</code>),

the user agent may create the ''::first-letter'' pseudo-element

(and its ''::prefix'' or ''::postfix'' sub-elements, if any)

from one of the elements, or all elements,

or simply not create the pseudo-element(s).

Additionally, if the [=first-letter text=]

is not at the start of the line

(for example due to bidirectional reordering,

or due to a [=list item=] [=marker=] with ''list-style-position: inside''),

then the user agent is not required to create the pseudo-element(s).

A ''::first-letter'' pseudo-element is contained within

any ''::first-line'' pseudo-elements,

and thus inherits (potentially indirectly) from ''::first-line'',

the same as any [=inline box=] on the same line.

<h4 id="first-letter-styling">

Styling the First-Letter Pseudo-elements</h4>

In CSS a ''::first-letter'' [=pseudo-element=]

(and its ''::prefix'' and ''::postfix'' sub-elements)

is similar to an [=inline box=].

The following properties apply to

''::first-letter'', ''::first-letter::prefix'', and ''::first-letter::postfix''

pseudo-elements:

<ul>

<li>all font properties (see [[CSS-FONTS-4]])

<li>the 'color' and 'opacity' properties (see [[CSS-COLOR-4]])

<li>all background properties (see [[CSS-BACKGROUNDS-4]])

<li>any typesetting properties that apply to inline elements (see [[CSS-TEXT-4]])

<li>all text decoration properties (see [[CSS-TEXT-DECOR-4]])

<li>any inline layout properties that apply to inline elements (see [[CSS-INLINE-3]])

<li>margin and padding properties (see [[CSS22]])

<li>border properties and 'box-shadow' (see [[CSS-BACKGROUNDS-4]])

<li>any other properties defined to apply to ''::first-letter''

by their respective specifications

</ul>

User agents may apply other properties as well.

However,

in no case may the application of such unlisted properties to ''::first-letter'' change

what [=first-letter text=] is represented by that ''::first-letter''.

Note: In previous levels of CSS,

user agents were allowed to choose a line height, width, and height

based on the shape of the letter,

to approximate font sizes;

and to take the glyph outline into account when performing layout.

The possibility of such loosely-defined magic has been intentionally removed,

as it proved to be a poor solution for the intended use case (drop caps and raised caps),

yet caused interoperability problems.

See 'initial-letter' in [[CSS-INLINE-3]]

for explicitly handling drop caps and raised caps.

<h2 id="highlight-pseudos">

Highlight Pseudo-elements</h2>

<h3 id="highlight-selectors">

Selecting Highlighted Content: the ''::selection'', ''::target-text'', ''::spelling-error'', and ''::grammar-error'' pseudo-elements</h3>

The <dfn export lt="highlight pseudo-element">highlight pseudo-elements</dfn>

represent portions of a document that have been given a particular status

and are typically styled differently to indicate that status to the user.

For example,

selected portions of the document are typically highlighted

(given alternate background and foreground colors, or a color wash)

to indicate their selected status.

The following <a>highlight pseudo-elements</a> are defined:

<dl export>

<dt><dfn>::selection</dfn>

<dd>

The ''::selection'' pseudo-element represents

the portion of a document that has been selected

as the target or object of some possible future user-agent operation(s).

It applies, for example, to selected text within an editable text field,

which would be copied by a copy operation or replaced by a paste operation.

<wpt>

css/css-pseudo/active-selection-001-manual.html

css/css-pseudo/active-selection-002-manual.html

css/css-pseudo/active-selection-004-manual.html

css/css-pseudo/active-selection-011.html

css/css-pseudo/active-selection-012.html

css/css-pseudo/active-selection-014.html

css/css-pseudo/active-selection-016.html

css/css-pseudo/active-selection-018.html

css/css-pseudo/active-selection-025.html

css/css-pseudo/active-selection-027.html

css/css-pseudo/active-selection-056.html

css/css-pseudo/active-selection-057.html

css/css-pseudo/active-selection-063.html

css/css-pseudo/selection-contenteditable-011.html

css/css-pseudo/selection-input-011.html

css/css-pseudo/selection-textarea-011.html

css/css-pseudo/textpath-selection-011.html

</wpt>

<dt><dfn>::target-text</dfn>

<dd>

The ''::target-text'' pseudo-element represents text

directly targeted by the document URL’s [=url/fragment=], if any.

Note: When a [=url/fragment|URL fragment=] targets an element,

the '':target'' pseudo-element can be used to select it,

but ''::target-text'' does not match anything.

It only matches text that is itself targeted by the [[=url/fragment=]].

<dt><dfn>::spelling-error</dfn>

<dd>

The ''::spelling-error'' pseudo-element represents

a portion of text that has been flagged by the user agent as misspelled.

<wpt>

css/css-pseudo/spelling-error-001.html

css/css-pseudo/spelling-error-002-manual.html

css/css-pseudo/spelling-error-003-manual.html

</wpt>

<dt><dfn>::grammar-error</dfn>

<dd>

The ''::grammar-error'' pseudo-element represents

a portion of text that has been flagged by the user agent as grammatically incorrect.

<wpt>

css/css-pseudo/grammar-error-001.html

css/css-pseudo/grammar-error-002-manual.html

css/css-pseudo/grammar-error-003-manual.html

</wpt>

</dl>

The <a>highlight pseudo-elements</a>

do not necessarily fit into the element tree,

and can arbitrarily cross element boundaries without honoring its nesting structure.

Note: A future level of CSS may introduce ways to create

custom highlight pseudo-elements.

<h3 id="highlight-styling">

Styling Highlights</h3>

The <a>highlight pseudo-elements</a> can only be styled

by a limited set of properties that do not affect layout

and can be applied performantly in a highly dynamic environment--

and additionally (to ensure interoperability)

whose rendering within the [[#highlight-bounds|required area]]

is not dependent on the exact (UA-determined) bounds

of the [=highlight overlay=].

The following properties apply to the <a>highlight pseudo-elements</a>:

<ul>

<li>'color'

<wpt>

css/css-pseudo/active-selection-001-manual.html

css/css-pseudo/active-selection-011.html

css/css-pseudo/active-selection-016.html

css/css-pseudo/active-selection-018.html

</wpt>

<li>'background-color'

<wpt>

css/css-pseudo/active-selection-002-manual.html

css/css-pseudo/active-selection-012.html

css/css-pseudo/active-selection-031.html

</wpt>

<li>'text-decoration' and its associated properties (including 'text-underline-position' and 'text-underline-offset')

<wpt>

css/css-pseudo/active-selection-004-manual.html

css/css-pseudo/active-selection-014.html

css/css-pseudo/active-selection-021.html

css/css-pseudo/grammar-error-001.html

css/css-pseudo/grammar-error-002-manual.html

css/css-pseudo/grammar-error-003-manual.html

css/css-pseudo/spelling-error-001.html

css/css-pseudo/spelling-error-002-manual.html

css/css-pseudo/spelling-error-003-manual.html

</wpt>

<li>'text-shadow'

<li>'stroke-color', 'fill-color', and 'stroke-width'

<wpt>

css/css-pseudo/textpath-selection-011.html

</wpt>

<li>[=custom properties=] [[!CSS-VARIABLES-1]]

</ul>

The 'forced-color-adjust' property cannot be set on [=highlight pseudo-elements=];

however a [=highlight pseudo-element=] must honor

any [=forced colors mode=] applied to its [=originating element=]

(and is therefore subject to the control of the [=originating element=]’s 'forced-color-adjust' value).

Issue: Are there any other properties that should be included here?

Note: The 'color' property sets the color of

both the text

and all line decorations (underline, overline, line-through)

and emphasis marks ('text-emphasis')

applied to the text

by the <a>originating element</a> and its ancestors and descendants.

<!-- Add this back if for some reason someone wants to implement 'outline'?

The outline, if supported, must be drawn

around the union of the active portions of the <a>highlight overlay</a>

precisely along the boundaries of those portions

and not between congruent parts.

The UA may use the outline styling of the nearest common ancestor

of any continuous or discontinuous range

rather than piecing together varying styles of outline

into a single shape.

-->

Note: Historically (and at the time of writing)

only 'color' and 'background-color' have been interoperably supported.

<h3 id=highlight-ua-styles>

Default UA Styles</h3>

The following additions are recommended for the default UA stylesheet:

<pre class="lang-css">

/* Represent default spelling/grammar error styling in an adjustable way */

:root::spelling-error { text-decoration-line: spelling-error; }

:root::grammar-error { text-decoration-line: grammar-error; }

</pre>

Some [=highlight pseudo-elements=]

should have <dfn>paired default highlight colors</dfn>--

a default 'color' and 'background-color'

provided by the UA

that are either used or overridden together,

see [[#paired-defaults]].

For ''::selection'' they should correspond to

''HighlightText'' and ''Highlight'',

while for ''::target-text'' they should correspond to

''MarkText'' and ''Mark''.

UAs may apply additional effects to enhance the presentation

of highlighted content,

for example dimming content other than the highlighted text

or transitioning out a highlight style based on user interactions or timing.

These are not controlled by CSS.

ISSUE: UA tweaks to the presentation of highlights

in ways that <em>are</em> controlled by CSS

are currently under discussion

in <a href='https://github.com/w3c/csswg-drafts/issues/6853'>Issue 6853</a>.

<h4 id="paired-defaults">

Paired Defaults</h4>

For compatibility reasons,

[=paired default highlight colors=]

must only be [=used value|used=]

when neither 'color' nor 'background-color'

yield a [=cascaded value=]

from the [=author origin=]

(or inherit their value from the author origin).

When a highlight color is ''revert'' or ''revert-layer'',

the origin <em>after</em> rolling back the cascade

determines the [=cascaded value=]’s [=cascade origin|origin=].

Note: Because this rule is for compatibility reasons,

it does not apply to other similar properties

like 'fill-color' or 'stroke-color'.

<div class="example">

For example,

given the following markup:

<pre class="lang-markup">

&lt;p>Highlight this &lt;em>and this&lt;/em>.&lt;/p>

</pre>

Any of the following rules

would suppress the default 'background-color'

for ''::selection''

in the <code>&lt;em></code> element

if given by the author:

<pre class="lang-css">

em::selection { color: initial; }

em::selection { color: inherit; }

em::selection { color: unset; }

em::selection { color: green; }

p::selection { color: green; }

</pre>

</div>

<wpt>

css/css-pseudo/highlight-paired-cascade-001.html

css/css-pseudo/highlight-paired-cascade-002.html

css/css-pseudo/highlight-paired-cascade-003.html

css/css-pseudo/highlight-paired-cascade-004.html

css/css-pseudo/highlight-paired-cascade-005.html

css/css-pseudo/highlight-paired-cascade-006.html

</wpt>

<h3 id=highlight-bounds>

Area of a Highlight</h3>

<p>For each type of highlighting (see [[#highlight-selectors]])

there exists a single <dfn>highlight overlay</dfn> for the entire document,

the active portions of which are represented

by the corresponding <a>highlight pseudo-element</a>.

Each box owns the piece of the overlay corresponding to any text or replaced content

directly contained by the box.

<ul>

<li>

For text, the corresponding overlay must cover at least the entire em box

and may extend further above/below the em box to the line box edges.

Spacing between two characters may also be part of the overlay area,

in which case it belongs to the innermost element that contains both characters

and is selected when both characters are selected.

<wpt>

css/css-pseudo/selection-intercharacter-011.html

css/css-pseudo/selection-intercharacter-012.html

</wpt>

<li>

For replaced content, the associated overlay must cover at least the entire replaced object,

and may extend outward to include the element's entire content box.

<wpt>

css/css-pseudo/active-selection-043.html

</wpt>

<li>

The overlay may also include other areas within the border-box of an element;

in this case, those areas belong to the innermost such element that contains the area.

<li>

For an [=inline-level box=], the overlay may extend outside its border edges

in the [=block axis=] as far as the edges of its [=line box=].

</ul>

Issue: See

<a href="http://lists.w3.org/Archives/Public/www-style/2008Nov/0022.html">F2F minutes</a>,

<a href="http://lists.w3.org/Archives/Public/www-style/2008Oct/0268.html">dbaron's message</a>,

<a href="http://lists.w3.org/Archives/Public/www-style/2010May/0247.html">Daniel's thread</a>,

<a href="http://lists.w3.org/Archives/Public/www-style/2010May/0261.html">Gecko notes</a>,

<a href="http://lists.w3.org/Archives/Public/www-style/2010May/0366.html">Opera notes</a>,

<a href="http://lists.w3.org/Archives/Public/www-style/2010May/0280.html">Webkit notes</a>

Issue: Not sure if this is the correct way of describing the way things work.

<h3 id=highlight-cascade>

Cascading and Per-Element Highlight Styles</h3>

Each element draws its own active portions of the <a>highlight overlays</a>,

which receives the styles specified by

the corresponding <a>highlight pseudo-element</a> styles

for which that element is the <a>originating element</a>.

When multiple styles conflict,

the winning style is determined by the cascade.

When any supported property is not given a value by the cascade,

or given a value of ''inherit'' or ''unset'',

its [=specified value=] is determined by inheritance from

the corresponding <a>highlight pseudo-element</a>

of its <a>originating element</a>'s parent element.

This occurs regardless of whether that property is an <a>inherited property</a>

(and regardless of whether that property is a [=custom property=]

that is registered to [=CSS/inherit=] or not).

Additionally, for [=highlight pseudo-elements=] originating from the [=root element=]:

<ul>

<li> the inherited value of 'color' is ''currentColor'', not the [=initial value=].

<li> [=custom properties=] inherit from the [=root element=].

</ul>

<wpt>

css/css-pseudo/active-selection-051.html

css/css-pseudo/active-selection-052.html

css/css-pseudo/active-selection-053.html

css/css-pseudo/active-selection-054.html

css/css-pseudo/cascade-highlight-004.html

</wpt>

<div class="example">

For example, if the following rules were applied:

<pre class="lang-css">

p::selection { color: yellow; background: green; }

p > em::selection { color: orange; }

em::selection { color: red; }

</pre>

to the following markup:

<pre class="lang-markup">

&lt;p>Highlight this &lt;em>and this&lt;/em>.&lt;/p>

</pre>

The selection highlight would be green throughout,

with yellow text outside the <code>&lt;em></code> element

and orange text inside it.

</div>

<wpt>

css/css-pseudo/cascade-highlight-001.html

</wpt>

<p class="advisement">

Authors wanting multiple selections styles should use

<strong>'':root::selection''</strong>

for their document-wide selection style,

since this will allow clean overriding in descendants.

''::selection'' alone applies to every element in the tree,

overriding the more specific styles of any ancestors.

<div class="example">

For example, if an author specified

<pre class="lang-css">

::selection { background: blue; }

p.warning::selection { background: red; }

</pre>

and the document included

<pre class="lang-markup">

&lt;p class="warning">Some &lt;strong>very important information&lt;/strong>&lt;/p>

</pre>

The highlight would be blue over “very important information”

because the <code>&lt;strong></code> element´s ''::selection''

also matches the ''::selection { background: blue; }'' rule.

(Remember that ''*'' is implied when a tag selector is missing.)

The style rules that would give the intended behavior

(red highlight within <code>p.warning</code>, blue elsewhere) are

<pre class="lang-css">

:root::selection { background: blue; }

p.warning::selection { background: red; }

</pre>

</div>

<wpt>

css/css-pseudo/cascade-highlight-002.html

</wpt>

The following example demonstrates the inheritance of [=custom properties=].

<div class="example">

For example, if an author specified

<pre class="lang-css">

:root {

--background-color: green;

--decoration-thickness: 10px;

--decoration-color: purple;

}

::selection {

--decoration-thickness: 1px;

--decoration-color: green;

}

div::selection {

--decoration-color: blue;

background-color: var(--background-color, red);

text-decoration-line: underline;

text-decoration-style: line;

text-decoration-thickness: var(--decoration-thickness, 5px);

text-decoration-color: var(--decoration-color, red);

}

</pre>

A div's selection highlight would be a green background to the

selected content, with a 1px thick blue underline. The

''--background-color'' custom property is not found on the

''div::selection'' nor ''::selection'' so it is taken from the

''::root'' custom property match. The ''--decoration-thickness''

property is inherited from ''::selection'' via the highlight

cascade and ''--decoration-color'' is found in

''div::selection'' itself.

</div>

Note: This behavior is intended to accomodate the standard practice of

defining document-wide custom properties on '':root''.

<h3 id="highlight-painting">

Painting the Highlight</h3>

<wpt>

css/css-pseudo/active-selection-014.html

css/css-pseudo/active-selection-041.html

css/css-pseudo/active-selection-045.html

css/css-pseudo/highlight-painting-001.html

css/css-pseudo/highlight-painting-002.html

css/css-pseudo/highlight-painting-003.html

css/css-pseudo/highlight-painting-004.html

</wpt>

<h4 id="highlight-backgrounds">

Backgrounds</h4>

Each <a>highlight pseudo-element</a> draws its background

over the corresponding portion of the <a>highlight overlay</a>,

painting it

immediately below any positioned descendants

(i.e. just before step 8 in <a href="https://www.w3.org/TR/CSS22/zindex.html#painting-order">CSS2.2&sect;E.2</a>).

<!-- Its outline, if any, is painted immediately over its background. -->

The ''::selection'' overlay is drawn