Highlight container specification

• Highlight container specification
  • Owned By
    • Requires approval from:
    • Signed off by:
    • Revision history
  • Overview
    • Acceptance criteria
  • User stories
    • End-user stories
    • Developer stories
  • Functionality
    • End-user experience
    • Developer experience
    • Localization
    • Keyboard navigation
  • API
    • Properties
    • Methods
    • Events
    • Slots
    • CSS Shadow Parts
    • CSS Variables
  • Test scenarios
    • Automation
  • Accessibility
    • References
    • RTL
  • Assumptions and limitations

Owned By

Team Name: Design and Web Development

Developer name: Radoslav Karaivanov

Designer name: Dilyana Yarabanova

Requires approval from:

• Damyan Petev
• Svilen Dimchevski

Signed off by:

• Simeon Simeonov
• Radoslav Mirchev

Revision history

Version	Author	Date	Notes
1	Radoslav Karaivanov	2026-03-11	Initial draft
1.1	Radoslav Karaivanov	2026-03-12	Renamed CSS variables

Overview

The igc-highlight allows for programmatic highlighting of DOM text nodes based on a set of criteria. It uses the browser native CSS Custom Highlight API and does not modify the page DOM in any way. It supports case-sensitive and case-insensitive matching, navigation between matches, and customizable highlight styling through CSS custom properties.

Acceptance criteria

The igc-highlight must:

• be WAI-ARIA compliant.
• not alter the DOM structure of slotted content.
• highlight all matching text occurrences for the given search string.
• visually distinguish the active highlight from the rest.
• support case-sensitive and case-insensitive matching.
• support programmatic navigation between matches with wrapping.
• support re-searching when slotted content changes dynamically.
• support custom styling of resting and active highlights via CSS custom properties.

User stories

End-user stories

As an end-user I expect to be able to:

• have a clear visual separation of the current highlighted text on the page.
• have a clear visual separation between the current active highlight and the rest.

Developer stories

As a developer I expect to be able to:

• set a search string and have the component match and highlight all applicable text.
• customize the highlight and active highlight visual styling.
• customize the search condition for matching and highlighting the text.
• customize the component to distinguishes between uppercase and lowercase letters in text.
• programmatically move the current active highlight in order to navigate the end-user.

Functionality

End-user experience

[Design Handoff]

Developer experience

Developers set the searchText property/attribute to initiate a search. All matching text nodes within the slotted content are highlighted using the CSS Custom Highlight API. The caseSensitive property controls whether matching is case-sensitive.

The size and current read-only properties expose the total number of matches and the index of the currently active match, respectively. The next(), previous(), and setActive() methods allow programmatic navigation between matches, with optional scroll-into-view behavior controlled via HighlightNavigation options.

When slotted content is dynamically changed, calling search() re-executes the highlight logic against the updated DOM.

Styling is applied through four CSS custom properties on the host: --background, --foreground, --background-active, and --foreground-active.

Localization

None applicable.

Keyboard navigation

None applicable since by default the component is non-focusable.

API

Properties

Property	Attribute	Reflected	Property Type	Default	Description
caseSensitive	case-sensitive	Yes	boolean	false	Whether to match the searched text with case sensitivity in mind.
searchText	search-text	No	string	''	The string to search and highlight in the DOM content of the component.
size	-	No	number	0	The total number of matches. Read-only.
current	-	No	number	0	The index of the currently active match. Read-only.

Methods

Name	Type signature	Description
next	(options?: HighlightNavigation): void	Moves the active state to the next match. Wraps around to the first match when at the end.
previous	(options?: HighlightNavigation): void	Moves the active state to the previous match. Wraps around to the last match when at the beginning.
setActive	(index: number, options?: HighlightNavigation): void	Moves the active state to the match at the given index.
search	(): void	Re-executes the highlight logic based on the current searchText and caseSensitive values. Useful when the slotted content is dynamic.

HighlightNavigation options:

Option	Type	Default	Description
preventScroll	boolean	false	If true, prevents the component from scrolling the new active match into view.

Events

None applicable.

Slots

Name	Description
default	Default slot for the igc-highlight. Search and highlight works only for content slotted into the component.

CSS Shadow Parts

None applicable.

CSS Variables

Name	Description
--foreground	The text color for a highlighted text node.
--background	The background color for a highlighted text node.
--foreground-active	The text color for the active highlighted text node.
--background-active	The background color for the active highlighted text node.

Test scenarios

Automation

• Verify that the component renders and is accessible (Shadow DOM and Light DOM a11y audits).
• Verify that setting searchText produces the correct number of matches.
• Verify that clearing searchText resets matches to 0.
• Verify case-insensitive matching by default (e.g. searchText="lorem" matches "Lorem").
• Verify case-sensitive matching when caseSensitive is true.
• Verify next() increments the current index.
• Verify previous() wraps around to the last match when at index 0.
• Verify setActive(index) sets the current index to the given value.
• Verify search() re-executes highlighting when slotted content is dynamically added or removed.
• Verify that initial search-text attribute produces matches on first render.

Accessibility

Since the highlight is visual only no intrinsic WAI-ARIA properties are applied. It is up to end-users to apply (if required) any accessibility attributes and relationships based on the application scenario they have.

References

• CSS Custom Highlight API
• CSS ::highlight() pseudo-element

RTL

The component should work in a Right-To-Left context without additional setup or configuration.

Assumptions and limitations

• The component matches text nodes which are its children. Any component which renders or portals content outside the parent igc-highlight container will not be included in the matches.

• The component matches only DOM text nodes. It does not support highlighting values inside inputs as well as any content that is set through the CSS content property.

• Shadow DOM roots are skipped while matching.