Search Box in Blazor Grid

• Jul 11, 2024
• 7 minutes to read

Set the ShowSearchBox property to true to display the search box in the Grid component.

Run Demo: Grid - Search Box

Once a user enters text into the box, the Grid looks for matches in the display text of every visible column. The search is case-insensitive. The component filters data to show only the rows with matching values. Data cells highlight the search results.

<DxGrid Data="Data" ShowSearchBox="true">
    <Columns>
        <DxGridDataColumn FieldName="ContactName"/>
        <DxGridDataColumn FieldName="City"/>
        <DxGridDataColumn FieldName="Country"/>
    </Columns>
</DxGrid>

If you use templates for data cells, the default mechanism does not apply highlighting to template content. You can use the template’s HighlightedDisplayText property to obtain the cell’s display text with highlighted search text.

You can customize the following search box settings:

SearchBoxInputDelay

Specifies the time interval between the last typed character in the search box and the consequent search text update.

SearchBoxNullText

Specifies the prompt text displayed in the search box when it is empty.

Users can press Ctrl+F to focus the search box.

Search Text in Code

Use the SearchText property to specify the search text in code. This property is in effect even if the search box is not visible. You can handle the SearchTextChanged event to respond to search text changes. The event is handled automatically when you use two-way data binding for the SearchText property (@bind-SearchText).

The following code snippet uses the SearchText property to implement an external search editor for the Grid.

<div class="d-flex py-2">
    <DxTextBox @bind-Text="SearchText" />
    <DxButton Text="Apply" Click="() => GridSearchText = SearchText" CssClass="mx-2" />
</div>
<DxGrid Data="Data" SearchText="@GridSearchText">
    <Columns>
        <DxGridDataColumn FieldName="CompanyName" />
        <DxGridDataColumn FieldName="ContactName" />
        <DxGridDataColumn FieldName="City" />
        <DxGridDataColumn FieldName="Country" />
    </Columns>
</DxGrid>
@code {
    object Data { get; set; }
    string SearchText { get; set; }
    string GridSearchText { get; set; }
}

Exclude Specific Columns from Search Operations

The Grid component seeks the search text in every visible column’s cells. Set a column’s SearchEnabled property to false to exclude a specific column from search operations.

<DxGrid Data="Data" ShowSearchBox="true" SearchBoxNullText="Search for a company...">
    <Columns>
        <DxGridDataColumn FieldName="CompanyName" />
        <DxGridDataColumn FieldName="ContactName" SearchEnabled="false"/>
        <DxGridDataColumn FieldName="City" SearchEnabled="false"/>
        <DxGridDataColumn FieldName="Country" SearchEnabled="false"/>
    </Columns>
</DxGrid>

Search Text Parse Mode

If a search text contains multiple words separated by space characters, the words can be treated as a single condition or individual conditions. Set the SearchTextParseMode property to one of the following values to specify how the Grid component treats search words.

GroupWordsByAnd

The search words are treated as individual conditions grouped by the AND logical operator. Only records that match all of the conditions are shown.

Search Text	Filter Condition	Result
anna canada	anna AND canada	finds every Anna, Annabelle, and Hanna that are from Canada

GroupWordsByOr

The search words are treated as individual conditions grouped by the OR logical operator. Records that match at least one of these conditions are shown.

Search Text	Filter Condition	Result
anna canada	anna OR canada	finds every Anna, Annabelle, and Hanna, and every person from Canada

ExactMatch

The search words are not treated separately. Only records that match the search text exactly are shown.

Search Text	Filter Condition	Result
anna canada	anna canada	finds every Anna Canada and Hanna Canada

Search Syntax

The search text can include special characters that allow users to create composite criteria. These characters are not in effect in the ExactMatch parse mode.

Group Operator for an Individual Criterion

+criterion

In GroupWordsByOr parse mode, precede a criterion with the plus sign to use the AND operator for this criterion. Other criteria are combined by the OR operator.

Search Text Sample	Description	Result Samples
maria anna +anders	contains either maria or anna, and must contain anders	Maria Anderson, Annabelle Anders

?criterion1 ?criterion2

In GroupWordsByAnd parse mode, precede criteria with the question mark to group them by the OR logical operator. Other criteria are combined by the AND operator.

Search Text Sample	Description	Result Samples
?maria ?anna anders	contains either maria or anna, and must contain anders	Maria Anderson, Annabelle Anders

Specify a Column for a Criterion

The Grid component seeks the search text in every visible data column if the column’s SearchEnabled property is set to true.

column:criterion

Precede a search string with the column’s caption plus a colon character to search against a specific column.

You can use the initial characters of the caption to search against the first column whose caption starts with the specified substring. To search against a column whose caption contains space characters, specify the column’s display caption in quotation marks.

Search Text Sample	Description	Result Samples
cont:maria	contains maria in a column whose caption starts with cont	Maria, Maria Anders
"contact name":maria	contains maria in a column whose caption starts with contact name	Maria, Maria Anders

If the specified column is not found, the Grid seeks the search text in every visible data column.

Criterion With Spaces

"word1 word2"

To search for a string that contains a space character, specify this string in quotation marks. Additionally, you can use the quotation mark to specify a column whose caption contains space characters.

Search Text Sample	Description	Result Samples
"maria anders"	contains maria anders	Maria Anders
"contact name":maria	contains maria in a column whose caption starts with contact name	Maria, Maria Anders

Logical Not

-criterion

Precede a criterion with the minus sign to exclude records that match this criterion from the result.

Search Text Sample	Description	Result Samples
maria -anders	contains maria but not anders	Maria Lopes

Comparison Operators

The Grid component uses the Contains operator to build search criteria. You can specify the following comparison operators for individual criterion.

^criterion

Precede a criterion with the caret sign to display records that start with the specified criterion.

=criterion

Precede a criterion with the equals sign to display records that are equal to the specified criterion.

Search Text Sample	Description	Result Samples
^anna	starts with anna	Annabelle Anders
=ana	equal to ana	Ana

Wildcard Masks

~criterion

Precede a condition with the tilde sign to use the following wildcard masks in a criterion.

• The % symbol - substitutes zero or more characters.
• The _ symbol - substitutes a single character.

Search Text Sample	Description	Result Samples
~an%o	starts with an and ends with o	Ana Trujillo
~%any	starts with any symbol(s) and ends with any	Germany
~_ran%	starts with any symbol, then ran, and ends with any symbol(s)	Francisco Chang, France

Search Box Position

The Grid displays the search box on the right side of the top panel.

If the group panel is visible, it is displayed on the left side of the same panel.

When the Grid has a small width, the search box is displayed above the group panel.

Customize Search Box Appearance

Handle the CustomizeElement event to customize the search box appearance. Compare the event argument’s e.ElementType property with the GridElementType.SearchBoxContainer value to determine whether the processed element is the search box.

<DxGrid Data="Data"
        PageSize="6"
        ShowSearchBox="true"
        CustomizeElement="Grid_CustomizeElement" >
    <Columns>
        <DxGridDataColumn FieldName="ContactName" />
        <DxGridDataColumn FieldName="CompanyName" />
        <DxGridDataColumn FieldName="City" />
        <DxGridDataColumn FieldName="Country" />
    </Columns>
</DxGrid>
@code {
    void Grid_CustomizeElement(GridCustomizeElementEventArgs e) {
        if(e.ElementType == GridElementType.SearchBoxContainer) {
            e.Style = "Width: 100%";
        }
    }
    // ...
}

Custom Search Box Editor

Use the SearchBoxTemplate property to implement custom content for the search box. The template accepts a GridSearchBoxTemplateContext object as the context parameter. You can use the parameter’s SearchText property to access the search text.

The following code snippet uses the DxSpinEdit<T> component to search for numbers in the Grid.

<DxGrid Data="Products" ShowSearchBox="true">
    <Columns>
        <DxGridDataColumn FieldName="ProductName" />
        <DxGridDataColumn FieldName="CategoryId" Caption="Category" />
        <DxGridDataColumn FieldName="UnitPrice" DisplayFormat="c" />
    </Columns>
    <SearchBoxTemplate> 
        <DxSpinEdit Value="GetSpinEditValue(context.SearchText)"
                    ValueChanged="(int? v) => context.SearchText = v.ToString()"
                    ClearButtonDisplayMode="DataEditorClearButtonDisplayMode.Auto" />
    </SearchBoxTemplate>
</DxGrid>
@code {
    int? GetSpinEditValue(string searchText) {
        if(string.IsNullOrEmpty(searchText))
            return null;
        return Convert.ToInt32(searchText);
    }
}

Limitations

The Grid component does not support search by display text when you use a Server Mode data source or GridDevExtremeDataSource. When you use these data sources, the Grid searches and filters data by cell values.