The CSS ::search-text pseudo-element selects matching text from your browser’s “find in page” feature. For example, if you use your browser search to find “search-text” on this page, all instances of it will highlight. This pseudo-element lets us style the appearance of that highlight.

And a bonus! If there are multiple matches on the page, then ::search-text can be used with the :current pseudo-class to style the match that’s currently in focus.

You can “find in page” using the CTRL + F (for Windows) or "⌘F" (for Mac) keyboard shortcuts.

::search-text {
  background: oklch(87% 0.17 90) /* yellow */;
  color: black;
}

::search-text:current {
  background: oklch(62% 0.22 38) /* red */;
  color: white;
}

The CSS ::search-text pseudo-element is defined in the CSS Pseudo-Elements Module Level 4 specification.

Syntax

Pretty straightforward! Declare the pseudo-element and add your style rules:

<element-selector>::search-text{
  /* ... */
}

Usage

It’s typically declared by itself (::search-text), but can be appended to specific elements as well:

/* All text */
::search-text {}
html::search-text {} /* kind of redundant */
/* Specific element */
section::search-text {}
strong::search-text {}

We’re a little limited as far as what CSS properties we can declare in ::search-text. Here is what it supports:

• background-color
• color
• text-decoration and its associated properties (text-underline-position and text-underline-offset), as well as its associated constituent properties:
  • text-decoration-color
  • text-decoration-line: But only the grammar-error, spelling-error, line-through, none, and underline values.
  • text-decoration-skip-ink
  • text-decoration-style
  • text-decoration-thickness
• text-shadow
• Custom properties

And, yes, we can use it with custom properties, like:

:root {
  --color-blueberry: oklch(0.5458 0.1568 241.39);
}
::search-text {
  background-color: var(--color-blueberry);
}

Basic usage

With the ::search-text pseudo-element, we can style the matching text results from “Find in page”. Plus, if we want to style the currently focused matching text, then we attach the :current pseudo-class after ::search-text.

/* matches all searched text */
::search-text {
  color: green;
  background-color: white;
}
/* matches any header level 1 searched text */
h1::search-text {
  text-shadow: 12px 1px lightgrey;
  background-color: black;
  color: white;
}
/* the current searched header level 1 text */
h1::search-text:current {
  color: red;
  background: white;
}

Inheritance chain

All descendants always inherit styles applied through the highlight pseudo-elements. This way, individual properties set on highlights will cascade to all elements down the three. Take for example the following HTML:

<article>
  <h2>Highlight inheritance demo</h2>
  <p>Lorem ipsum dolor sit amet. <strong>Lorem</strong> appears again here. Another lorem appears here.
  </p>
</article>

We have an <article> container with two children: <h2> and <p>, the latter having a <strong> descendant of its own. We could style ::search-text in <article> with the following CSS, which would apply to all elements in <article>:

article::search-text {
  background: gold;
  color: black;
  text-decoration: underline;
}

Then, override the color property for only <p> and its descendants:

p::search-text {
  color: orange;
}

And do the same for text-decoration on the <strong> element:

strong::search-text {
  text-decoration: line-through;
}

When you search for “lorem”, the background of the first instance (inside <p> but outside <strong>) will inherit both the background and text-decoration values from <article>, while overriding its color value with its own orange.

Onto <strong>‘s “lorem” text, it will inherit the properties we set in its parent <p> and grandparent <article. So the color and background values are inherited directly from its parent, and since they haven’t been overridden, they stay. While we override the text-decoration value to line-through.

The key takeaway from this example is that properties for highlight elements are also individually inherited and overridden.

Targeting a text

In the demo below, we set text-decoration to underline to give any searched text a blue underline. This way, we can customize matching text while also leaving the default background color, which prevents people from getting confused about what’s going on.

::search-text {
  text-decoration: underline;
  text-decoration-color: oklch(65% 0.18 240);
  text-decoration-thickness: 0.22em;
  text-underline-offset: 0.15em;
}

Using :current

Using ::search-text with :current, we can style the currently focused match. For example, below we apply a light orange hue text decoration color with 0.3em thickness to the currently matched searched text:

::search-text:current {
  text-decoration-color: oklch(85% 0.22 38);
  text-decoration-thickness: 0.3em;
}

Some accessibility notes

For WCAG’s contrast standards, you need a contrast ratio of at least 4.5:1 between the text and background. Another piece of advice is not to change the search colors too much. In fact, this feature should be used sparingly since it may cause issues for users with cognitive issues, and as a core part of the browser, it can be generally confusing. My personal advice is to stick to only text-decoration and its associated properties since they are more subtle than the rest.

There’s also :past and :future

The :past and :future pseudo-classes are supposed to match the element entirely prior and entirely after a :current element, respectively.

However, the specification says:

The :past and :future pseudo-classes are reserved for analogous use in the future. Any unsupported combination of these pseudo-classes with ::search-text must be treated as invalid

Meaning, you can’t use :past, :future or any other pseudo-class with the ::search-text pseudo-element. If your browser somehow works with them, kindly report the unexpected behavior by opening an issue with them.

Specification

The CSS ::search-text pseudo-element is defined in the CSS Pseudo-Elements Module Level 4 specification. This is still being tested and improved upon.

Browser support

Very wide support: