<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., [email protected], 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

WPT Path Prefix: css/css-pseudo/

WPT Display: closed

</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

spec:css-lists-3; type:dfn; text:marker

spec:css-backgrounds-3; type:property; text:box-shadow

</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]].

Note: As a reminder,

pseudo-elements cannot be chained together unless explicitly allowed.

For example, ''::marker::before'' is not allowed;

but ''::before::marker'' is.

<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=].

<wpt>

first-line-allowed-properties.html

first-line-and-marker.html

first-line-and-placeholder.html

first-line-change-inline-color-nested.html

first-line-change-inline-color.html

first-line-first-letter-insert-crash.html

first-line-float-mapped-attribute-crash.html

first-line-inherited-no-transition.html

first-line-inherited-transition-crash.html

first-line-inherited-with-transition.html

first-line-input-image-crash.html

first-line-line-height-001.html

first-line-line-height-002.html

first-line-nested-gcs.html

first-line-on-ancestor-block.html

first-line-opacity-001-ref.html

first-line-opacity-001.html

first-line-replaced-001.html

first-line-with-before-after.html

first-line-with-inline-block-before.html

first-line-with-inline-block.html

first-line-with-out-of-flow-and-nested-div.html

first-line-with-out-of-flow-and-nested-span.html

first-line-with-out-of-flow.html

</wpt>

<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-3]])

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

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

<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>

<wpt>

first-letter-001.html

first-letter-002.html

first-letter-003.html

first-letter-004.html

first-letter-005.html

first-letter-allowed-properties.html

first-letter-and-sibling-display-change.html

first-letter-and-whitespace.html

first-letter-background-image-dynamic.html

first-letter-background-image.html

first-letter-bidi-pre-crash.html

first-letter-block-to-inline.html

first-letter-crash.html

first-letter-digraph.html

first-letter-exclude-block-child-marker.html

first-letter-exclude-inline-child-marker.html

first-letter-exclude-inline-marker.html

first-letter-hi-001.html

first-letter-hi-002.html

first-letter-list-item-dynamic-001.html

first-letter-of-html-root-refcrash.html

first-letter-opacity-001-ref.html

first-letter-opacity-001.html

first-letter-opacity-float-001.html

first-letter-punctuation-and-space.html

first-letter-punctuation-dynamic.html

first-letter-skip-empty-span-nested.html

first-letter-skip-empty-span.html

first-letter-skip-marker.html

first-letter-text-and-display-change.html

first-letter-width-2.html

first-letter-width.html

first-letter-with-before-after.html

first-letter-with-preceding-new-line.html

first-letter-with-quote.html

first-letter-with-span.html

</wpt>

<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'', ''::search-text'', ''::target-text'', ''::spelling-error'', ''::grammar-error'', and ''::highlight()'' pseudo-elements</h3>

<wpt>

grammar-spelling-errors-001.html

grammar-spelling-errors-002.html

highlight-cascade/cascade-highlight-001.html

highlight-cascade/cascade-highlight-002.html

highlight-cascade/cascade-highlight-004.html

highlight-cascade/cascade-highlight-005.html

highlight-cascade/highlight-cascade-001.html

highlight-cascade/highlight-cascade-003.html

highlight-cascade/highlight-cascade-004.html

highlight-cascade/highlight-cascade-005.html

highlight-cascade/highlight-cascade-006.xhtml

highlight-cascade/highlight-cascade-007.html

highlight-cascade/highlight-cascade-008.html

highlight-cascade/highlight-cascade-009.html

highlight-cascade/highlight-currentcolor-computed-inheritance.html

highlight-cascade/highlight-currentcolor-computed-visited.html

highlight-cascade/highlight-currentcolor-computed.html

highlight-cascade/highlight-currentcolor-painting-properties-001.html

highlight-cascade/highlight-currentcolor-painting-properties-002.html

highlight-cascade/highlight-currentcolor-painting-text-shadow-001.html

highlight-cascade/highlight-currentcolor-painting-text-shadow-002.html

highlight-cascade/highlight-currentcolor-root-explicit-default-001.html

highlight-cascade/highlight-currentcolor-root-explicit-default-002.html

highlight-cascade/highlight-currentcolor-root-implicit-default-001.html

highlight-cascade/highlight-currentcolor-root-implicit-default-002.html

highlight-cascade/highlight-pseudos-computed.html

highlight-cascade/highlight-pseudos-inheritance-computed-001.html

highlight-cascade/highlight-pseudos-visited-computed-001.html

highlight-custom-properties-dynamic-001.html

highlight-painting-005-crash.html

highlight-painting-currentcolor-001.html

highlight-painting-currentcolor-001a.html

highlight-painting-currentcolor-002.html

highlight-painting-currentcolor-002a.html

highlight-painting-currentcolor-002b.html

highlight-painting-currentcolor-003.html

highlight-painting-currentcolor-003a.html

highlight-painting-currentcolor-003b.html

highlight-painting-currentcolor-004.html

highlight-painting-currentcolor-004a.html

highlight-painting-currentcolor-004b.html

highlight-painting-currentcolor-005.html

highlight-painting-shadows-horizontal.html

highlight-painting-shadows-vertical.html

highlight-painting-soft-hyphens-001.html

highlight-painting-soft-hyphens-002-crash.html

highlight-styling-001.html

highlight-styling-002.html

parsing/highlight-pseudos.html

</wpt>

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>

active-selection-001-manual.html

active-selection-002-manual.html

active-selection-004-manual.html

active-selection-011.html

active-selection-012.html

active-selection-014.html

active-selection-016.html

active-selection-018.html

active-selection-025.html

active-selection-027.html

active-selection-056.html

active-selection-057.html

active-selection-063.html

selection-background-color-001.html

selection-link-001.html

selection-link-002.html

selection-link-003.html

selection-over-highlight-001.html

selection-universal-shadow-dom.html

selection-contenteditable-011.html

selection-input-011.html

selection-textarea-011.html

textpath-selection-011.html

</wpt>

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

<dd>

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

identified by the user agent’s find-in-page feature.

Since not all UAs style matched text in ways

expressible with the [=highlight pseudo-elements=],

this pseudo-element is optional to implement.

Issue(10527): How to identify the current match?

<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=]].

<wpt>

target-text-001.html

target-text-002.html

target-text-003.html

target-text-004.html

target-text-005.html

target-text-006.html

target-text-007.html

target-text-008.html

target-text-009.html

target-text-010.html

target-text-dynamic-001.html

target-text-dynamic-002.html

target-text-dynamic-003.html

target-text-dynamic-004.html

target-text-shadow-horizontal.html

target-text-shadow-vertical.html

target-text-text-decoration-001.html

</wpt>

<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>

spelling-error-001.html

spelling-error-002-manual.html

spelling-error-003-manual.html

spelling-error-004-crash.html

spelling-error-005-crash.html

spelling-error-006.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>

grammar-error-001.html

grammar-error-002-manual.html

grammar-error-003-manual.html

</wpt>

<dt><dfn>::highlight(<<custom-ident>>)</dfn>

<dd>

The ''::highlight()'' [=functional pseudo-element=] represents

the portion of the document associated with the [=custom highlight=]

identified by the given [=custom highlight name=].

The <<custom-ident>> argument is required.

See [[CSS-HIGHLIGHT-API-1]] for details.

<wpt>

css/css-highlight-api/painting/custom-highlight-painting-001.html

css/css-highlight-api/painting/custom-highlight-painting-002.html

css/css-highlight-api/painting/custom-highlight-painting-003.html

css/css-highlight-api/painting/custom-highlight-painting-004.html

css/css-highlight-api/painting/custom-highlight-painting-005.html

css/css-highlight-api/painting/custom-highlight-painting-006.html

css/css-highlight-api/painting/custom-highlight-painting-007.html

css/css-highlight-api/painting/custom-highlight-painting-008.html

css/css-highlight-api/painting/custom-highlight-painting-009.html

css/css-highlight-api/painting/custom-highlight-painting-010.html

css/css-highlight-api/painting/custom-highlight-painting-011.html

css/css-highlight-api/painting/custom-highlight-painting-012.html

css/css-highlight-api/painting/custom-highlight-painting-013.html

css/css-highlight-api/painting/custom-highlight-painting-014.html

css/css-highlight-api/painting/custom-highlight-painting-015.html

css/css-highlight-api/painting/custom-highlight-painting-iframe-001.html

css/css-highlight-api/painting/custom-highlight-painting-iframe-002.html

css/css-highlight-api/painting/custom-highlight-painting-iframe-003.html

css/css-highlight-api/painting/custom-highlight-painting-iframe-004.html

css/css-highlight-api/painting/custom-highlight-painting-iframe-005.html

css/css-highlight-api/painting/custom-highlight-painting-iframe-006.html

css/css-highlight-api/painting/custom-highlight-painting-invalidation-001.html

css/css-highlight-api/painting/custom-highlight-painting-invalidation-002.html

css/css-highlight-api/painting/custom-highlight-painting-invalidation-003.html

css/css-highlight-api/painting/custom-highlight-painting-invalidation-004.html

css/css-highlight-api/painting/custom-highlight-painting-invalidation-005.html

css/css-highlight-api/painting/custom-highlight-painting-invalidation-006.html

css/css-highlight-api/painting/custom-highlight-painting-invalidation-007.html

css/css-highlight-api/painting/custom-highlight-painting-prioritization-001.html

css/css-highlight-api/painting/custom-highlight-painting-prioritization-002.html

css/css-highlight-api/painting/custom-highlight-painting-staticrange-001.html

css/css-highlight-api/painting/custom-highlight-painting-staticrange-002.html

css/css-highlight-api/painting/custom-highlight-painting-staticrange-003.html

css/css-highlight-api/painting/custom-highlight-painting-staticrange-004.html

css/css-highlight-api/painting/custom-highlight-painting-staticrange-005.html

css/css-highlight-api/painting/custom-highlight-painting-staticrange-006.html

css/css-highlight-api/painting/custom-highlight-painting-staticrange-007.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.

<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>

active-selection-001-manual.html

active-selection-011.html

active-selection-016.html

active-selection-018.html

</wpt>

<li>'background-color'

<wpt>

active-selection-002-manual.html

active-selection-012.html

active-selection-031.html

</wpt>

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

<wpt>

active-selection-004-manual.html

active-selection-014.html

active-selection-021.html

grammar-error-001.html

grammar-error-002-manual.html

grammar-error-003-manual.html

spelling-error-001.html

spelling-error-002-manual.html

spelling-error-003-manual.html

</wpt>

<li>'text-shadow'

<wpt>

marker-text-shadow.html

</wpt>

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

<wpt>

textpath-selection-011.html

</wpt>

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

</ul>

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

Note: Historically (and at the time of writing)

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

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.

For any properties not listed above,

but which are required to resolve the values of applicable properties,

their [=computed values=] are copied from those of the [=originating element=],

ignoring any values specified on the [=highlight pseudo-element=] itself.

For example:

<ul>

<li>'forced-color-adjust' (used in [=forced colors mode=] to resolve colors)

and 'color-scheme' (used to resolve [=system colors=])

<li>'font-size', 'font-family', etc. (used to resolve ''em'' and other [=font-relative lengths=]).

<li>'line-height' (used to resolve ''lh'' units)

<li>[=custom properties=] [[!CSS-VARIABLES-1]] (used in ''var()'' substitutions)

</ul>

<!-- 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.

-->

If, for a given [=highlight pseudo-element=],

there are colors specified in the [=author origin=],

those colors must be respected as specified;

i.e. the UA must not apply any extra processing

(such as using semi-transparent washes).

However if there are no colors in the [=author origin=],

the UA may apply additional color processing.

Note: This is to ensure that color contrast is preserved

across all user agents interpreting a given author stylesheet.

Vendor-prefixed properties such as '-webkit-text-fill-color'

are not applicable to the [=highlight pseudo-elements=].

<!-- https://github.com/w3c/csswg-drafts/issues/7580 -->

<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: spelling-error; }

:root::grammar-error { text-decoration: 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>.