React Highlight Overview

Ignite UI for React Highlight is used to highlight parts of the page content to make it more noticeable for the user. It’s a lightweight component that can be used in combination with other components to create a more interactive and engaging user experience.

Usage

To use the IgrHighlight component, all you need to do is wrap its tags around the content you want to search. The component searches the content of all nested elements within the <IgrHighlight> tags, and highlights all matches of the specified string.

The IgrHighlight component searches only DOM text nodes. It does not search input values or content set via the CSS content property.

First, you need to install the Ignite UI for React by running the following command:

npm install igniteui-react

You will then need to import the IgrHighlight and its necessary CSS, like so:

import { IgrHighlight } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

For a complete introduction to the Ignite UI for React, read the Getting Started topic.

The simplest way to start using the IgrHighlight component is as follows:

<IgrHighlight search-text='dolor'>
    <p>Lorem ipsum dolor sit, amet consectetur adipisicing elit.</p>
</IgrHighlight>

The <IgrHighlight> tags wrap the content in which you want to highlight the specific string.

The text to be highlighted is set via the search-text attribute. In the example above, the word “dolor” will be highlighted.

Case Sensitive Match

The IgrHighlight component also exposes a case-sensitive attribute. Its default value is false, which enables case-insensitive matching. By setting it to true, you can enable case-sensitive matching.

The following snippet:

<IgrHighlight search-text='lorem' case-sensitive={true}>
    <p>Lorem ipsum dolor sit, amet consectetur adipisicing elit.</p>
</IgrHighlight>

This returns 0 matches because the search text “lorem” is in lowercase, while the text in the content is Lorem with an uppercase L.

Using Highlight with a Search Input

The most common use case is binding the IgrHighlight component to a search IgrInput component, so that search matches are highlighted in real time as the user types.

To bind the two together, you can listen to the igcInput event of the IgrInput component and set the search-text attribute of the IgrHighlight component to the input value every time the event is fired (you can also use the standard input event).

First, you need to access the IgrHighlight component to manipulate its properties. The easiest way to do this is via a reference:

import { useRef } from 'react';

const highlightRef = useRef<IgrHighlight>(null);

<IgrHighlight ref={highlightRef}>
    ...
</IgrHighlight>

Then, create a function that updates the search text, called every time the igcInput event fires:

const onInput = ({ detail }: CustomEvent<string>) => {
    highlightRef.current.searchText = detail;
};

<IgrInput label="Search" onigcInput={onInput}></IgrInput>

Methods

The component also exposes two methods for navigating the search matches. The next() method moves to the next match, while the previous() method moves to the previous one.

With them, we can make the search more interactive by adding two buttons to navigate between matches:

const highlightRef = useRef<IgrHighlight>(null);

const prev = () => {
    highlightRef.current?.previous();
};

const next = () => {
    highlightRef.current?.next();
};

<IgrInput label="Search">
    <IgrIconButton onClick={prev} variant="flat" name="navigate_before" collection="internal" slot="suffix"></IgrIconButton>
    <IgrIconButton onClick={next} variant="flat" name="navigate_next" collection="internal" slot="suffix"></IgrIconButton>
</IgrInput>

Both the previous() and next() methods accept a IgrHighlight.preventScroll option that prevents the page from scrolling to the active match during navigation. By default, it is set to false.

const prev = () => {
    highlightRef.current?.previous({ preventScroll: true });
};

const next = () => {
    highlightRef.current?.next({ preventScroll: true });
};

Additional Features

The component also exposes two read-only properties for tracking match state: size returns the total number of matches, and current returns the index of the active match.

They are useful for building a search status indicator that shows the user which match they are on and how many matches exist in total.

Here is a simple example of how to use those properties to create a search status:

const highlightRef = useRef<IgrHighlight>(null);
const statusRef = useRef<HTMLParagraphElement>(null);

const updateStatus = () => {
    const highlight = highlightRef.current;
    const status = statusRef.current;

    status.textContent = highlight.size
      ? `${highlight.current + 1} of ${highlight.size} match${highlight.size === 1 ? '' : 'es'}`
      : '';
}

We can then call updateStatus() every time the input value changes or the user clicks the next or previous buttons:

const onInput = ({ detail }: CustomEvent<string>) => {
    highlightRef.current.searchText = detail;
    updateStatus();
};

const prev = () => {
    highlightRef.current?.previous();
    updateStatus();
};

const next = () => {
    highlightRef.current?.next();
    updateStatus();
};

<IgrInput label="Search" onigcInput={onInput}>
    <IgrIconButton onClick={prev} variant="flat" name="navigate_before" collection="internal" slot="suffix" ></IgrIconButton>
    <IgrIconButton onClick={next} variant="flat" name="navigate_next" collection="internal" slot="suffix" ></IgrIconButton>
    <p ref={statusRef} slot="helper-text"></p>
</IgrInput>

<IgrHighlight ref={highlightRef}>

Styling

The IgrHighlight component exposes four CSS variables which can be used to style the whole component:

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

igc-highlight {
    --background: var(--ig-gray-700);
    --foreground: var(--ig-gray-700-contrast);
    --background-active: var(--ig-warn-500);
    --foreground-active: var(--ig-warn-500-contrast);
}