"When I search for terms in the FAQ, the matching areas are highlighted in yellow, but the text inside cannot be read"—this is a frequent complaint received in client web development projects for manuals, FAQs, and documentation portals. The highlights applied to matches in browser in-page search (Ctrl+F / Cmd+F) do not account for a site's specific color palette. On dark themes or saturated backgrounds, default bright browser highlights clash with text colors, rendering the exact words being searched for virtually illegible. Attempting to fix this by traversing the DOM with JavaScript and wrapping hits in <span> creates a custom highlight system that demands its own maintenance and duplicates browser-native search functionality.
This issue can be solved without custom implementations by styling the browser's search highlight directly using CSS. As covered in ::search-text (CSS-Tricks Almanac) published by CSS-Tricks in June 2026, pseudo-elements targeting text matched via in-page search are now available. In this article, we explore how to ensure search results remain readable on documentation sites in client web development using only CSS.
Why unreadable search highlights happen
In-page search highlights are user experience features provided by browsers and are rendered independently of a site's CSS. Most browsers default to black text on a bright yellow or orange background. While this causes no issues on plain pages with white backgrounds and black text, real-world sites built for clients present very different conditions.
When this highlight overlays dark-theme body text with light typography, light text sits on a light highlight background, wiping out contrast entirely. Conversely, on areas styled with rich brand background colors, the yellow highlight clashes and degrades visibility. As a result, the moment text is highlighted, that specific word becomes unreadable—the exact opposite of search's intended purpose.
Historically, solutions to this were limited. The common workaround was leaving browser search styling untouched and writing JavaScript to scan the body text and inject custom highlights, but this comes at a significant cost.
| Workaround | Issues |
|---|---|
| Do nothing (keep browser defaults) | Highlighted sections become unreadable depending on color schemes |
| Custom highlight by scanning text with JS | Implementation maintenance costs, duplication of native search, side effects from DOM mutations |
| Style standard highlights with ::search-text | CSS-only, retains native search while adjusting only visual presentation |
::search-text makes this third option viable. By utilizing the browser's native in-page search functionality as-is and overriding only the visual styling of matches to match the site's palette, no JavaScript or DOM manipulation is required.
::search-text basics — overriding default search styling
Using it is straightforward: simply specify background and text colors in CSS for search-matched text.
/* ページ内検索のヒット箇所をサイトの配色に合わせる */
::search-text {
background-color: #ffd54f; /* サイトのアクセント色 */
color: #1a1a1a; /* その上で確実に読める文字色 */
}
/* いま選択中のヒット（次へ送りで強調される箇所）を区別する */
::search-text:current {
background-color: #ff8a3d;
color: #ffffff;
}The key element is ::search-text:current. In-page search typically applies a subtle highlight to all matches while emphasizing the currently selected match more prominently. Pairing this with :current allows styling all hits and the current match differently, ensuring users do not lose track of which occurrence they are viewing. Achieving this in custom implementations requires considerable effort, making the ability to accomplish it via CSS while leveraging native functionality a substantial benefit.
Note that ::search-text is restricted primarily to color and text-decoration properties; properties that alter layout cannot be used. The proper use case should remain strictly focused on adjusting default highlight colors into readable combinations.
Guaranteeing contrast as an accessibility requirement
The goal of implementing ::search-text is not visual preference, but ensuring readability. If the contrast ratio between the highlight background and the text color is insufficient, you land right back where you started with unreadable matches. When assigning colors, always verify that the combination provides adequate contrast.
For sites supporting dark and light themes, configure separate ::search-text palettes for each theme.
/* ライトテーマ */
::search-text { background-color: #ffe08a; color: #1a1a1a; }
/* ダークテーマ */
[data-theme="dark"] ::search-text {
background-color: #5b73ff;
color: #ffffff;
}By designing color palettes as part of your theme system, you ensure search highlights remain legible under every theme. Guaranteeing color pairings systematically rather than through scattered hardcoded values follows the same philosophy as our article on self-correcting color systems with contrast-color(). Treating search highlights as another domain governed by your color system brings consistency to your design.
Keep in mind that ::search-text targets matches from browser in-page search (Ctrl+F), which is distinct from result highlights within custom search forms embedded on a page. Avoid confusing the two; when considering the overall site search experience, pairing this with the principle of guiding users to their destination as quickly as possible—as detailed in our article on site search UX—will help cover every aspect of the search journey.
Pitfalls when adopting it in client web development
On an operations manual site for an enterprise system whose maintenance we took over (company name withheld), enterprise clients repeatedly submitted inquiries stating that text became invisible against the background during in-page searches under the dark theme. The prior vendor had addressed this with a custom JavaScript script that scanned the body DOM and wrapped search terms in <span> to apply highlights. Because this ran alongside the browser's native Ctrl+F, highlights nested inside one another and caused visual rendering bugs.
We removed the custom highlight implementation, unified search under the browser's native in-page feature, and styled the palette for both light and dark themes using ::search-text and ::search-text:current. We simply returned a duplicated custom function to native browser behavior and adjusted its visual appearance with CSS to ensure readable colors. Consequently, search hits became readable across all themes, and removing the DOM-mutating script resolved secondary issues affecting text copying and screen readers.
The most impactful lesson from this project was never rebuilding native browser capabilities with JavaScript unnecessarily. For OS- and browser-level experiences like search highlights, users are already familiar with how they behave. Replacing them with custom implementations increases maintenance burden and triggers conflicts with native functions. Staying aligned with standards and using CSS only to address shortcomings—such as palette readability—yields a lighter, far more resilient implementation.
Another pitfall involves variations in browser support. On browsers that do not recognize ::search-text, highlights simply render using default browser styles. Because this provides graceful degradation—improving readability where supported while leaving unsupported browsers unchanged—the risk of adoption is low. However, you cannot promise clients identical rendering across all browsers, so prepare to explain support boundaries using the Baseline framework described in our article on modern native CSS features.
Where to begin
If you are handling client web development for documentation, FAQs, or manuals where users actively search body text, we recommend testing your site with in-page search under a dark theme or on saturated background sections. If matches are difficult to read, that is an immediate candidate for ::search-text.
The initial step is to write a single ::search-text rule combining your site's accent color for the background with a clearly readable text color, distinguishing the active match using :current. If your site supports theme toggling, remember to define palettes for each theme. If a custom highlight script is already active, evaluate whether it can be retired in favor of native search.
If search highlights on your manual or FAQ sites are illegible, or if custom highlight scripts have become bloated and difficult to maintain, please reach out via the GleamHub contact form. We can assess your existing search experience and optimize it to ensure readability and accessibility through native platform features.
