Open Source

Blazor Highlight Overview

Ignite UI for Blazor 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 IgbHighlight 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 <IgbHighlight> tags, and highlights all matches of the specified string.

The IgbHighlight 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 Blazor by running the following command:

dotnet add package IgniteUI.Blazor --version 26.1.98

// in Program.cs file

builder.Services.AddIgniteUIBlazor(typeof(IgbHighlightModule));

You also need to reference the corresponding styles based on your project configuration.

<link href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />

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

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

<IgbHighlight SearchText="dolor">
    <p>Lorem ipsum dolor sit, amet consectetur adipisicing elit.</p>
</IgbHighlight>

The <IgbHighlight> 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 IgbHighlight 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:

<IgbHighlight SearchText="lorem" CaseSensitive="true">
    <p>Lorem ipsum dolor sit, amet consectetur adipisicing elit.</p>
</IgbHighlight>

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 IgbHighlight component to a search IgbInput 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 IgbInput component and set the search-text attribute of the IgbHighlight component to the input value every time the event is fired (you can also use the standard input event).

First, you need to add the searchText property:

private string searchText = "";

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

private void OnValueChanging(string newValue)
{
    searchText = newValue;
}

<IgbInput Label="Search" ValueChanging="OnValueChanging"></IgbInput>
<IgbHighlight SearchText="@searchText">
    <p>
        Lorem ipsum dolor sit, amet consectetur adipisicing elit. Quae doloribus
        odit id excepturi ipsum provident eaque dignissimos beatae! Rerum vero
        distinctio libero, quasi magni quod natus nesciunt doloremque temporibus
        voluptate?
    </p>
</IgbHighlight>

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:

private IgbHighlight HighlightRef { get; set; }

private async Task Prev()
{
    if (HighlightRef != null)
        await HighlightRef.PreviousAsync(new IgbHighlightNavigation());
}

private async Task Next()
{
    if (HighlightRef != null)
        await HighlightRef.NextAsync(new IgbHighlightNavigation());
}

<IgbInput Label="Search" ValueChanging="OnValueChanging">
    <IgbIconButton slot="suffix" Variant="IconButtonVariant.Flat" IconName="navigate_before" Collection="internal" @onclick="Prev"></IgbIconButton>
    <IgbIconButton slot="suffix" Variant="IconButtonVariant.Flat" IconName="navigate_next" Collection="internal" @onclick="Next"></IgbIconButton>
</IgbInput>

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

private async Task Prev()
{
    if (HighlightRef != null)
        await HighlightRef.PreviousAsync(new IgbHighlightNavigation { PreventScroll = true });
}

private async Task Next()
{
    if (HighlightRef != null)
        await HighlightRef.NextAsync(new IgbHighlightNavigation { PreventScroll = true });
}

Additional Features

The component also exposes two async methods for tracking match state: GetSizeAsync() returns the total number of matches, and GetCurrentAsync() returns the index of the active match.

These methods 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 these methods to create a search status:

private async Task UpdateStatus()
{
    var size = (int)await HighlightRef.GetSizeAsync();
    var current = (int)await HighlightRef.GetCurrentAsync();
    helperText = $"{current + 1} of {size} match{(size == 1 ? "" : "es")}";
}

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

private async Task Prev()
{
    await HighlightRef.PreviousAsync(new IgbHighlightNavigation());
    await UpdateStatus();
    StateHasChanged();
}

private async Task Next()
{
    await HighlightRef.NextAsync(new IgbHighlightNavigation());
    await UpdateStatus();
    StateHasChanged();
}

<IgbInput Label="Search" ValueChanging="OnValueChanging">
            <IgbIconButton slot="suffix" Variant="IconButtonVariant.Flat" IconName="navigate_before" Collection="internal" @onclick="Prev"></IgbIconButton>
            <IgbIconButton slot="suffix" Variant="IconButtonVariant.Flat" IconName="navigate_next" Collection="internal" @onclick="Next"></IgbIconButton>
            <p slot="helper-text">@helperText</p>
</IgbInput>

<IgbHighlight @ref="HighlightRef">

Styling

The IgbHighlight 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);
}

API References

IgbHighlight