Skip to content

Merge grid-search-3435 into production #3436

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dimodi merged 1 commit into from
Jan 9, 2026
Merged

Merge grid-search-3435 into production #3436

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 43 additions & 37 deletions _contentTemplates/grid/state.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -396,14 +396,16 @@
Data="@GridData"
Pageable="true"
Sortable="true">
<GridToolBarTemplate>
<GridSearchBox />
<TelerikButton Icon="@SvgIcon.Search"
ThemeColor="@ThemeConstants.Button.ThemeColor.Primary"
OnClick="@OnSearchButtonClick">Search Programmatically</TelerikButton>
<TelerikButton Icon="@SvgIcon.X"
OnClick="@OnClearButtonClick">Clear Search</TelerikButton>
</GridToolBarTemplate>
<GridToolBar>
<GridToolBarCustomTool>
<TelerikButton Icon="@SvgIcon.Search"
ThemeColor="@ThemeConstants.Button.ThemeColor.Primary"
OnClick="@OnSearchButtonClick">Search Programmatically</TelerikButton>
<TelerikButton Icon="@SvgIcon.X"
OnClick="@OnClearButtonClick">Clear Search</TelerikButton>
</GridToolBarCustomTool>
<GridToolBarSearchBoxTool />
</GridToolBar>
<GridColumns>
<GridColumn Field="@nameof(GridModel.Name)" />
<GridColumn Field="@nameof(GridModel.Description)" />
Expand All @@ -417,49 +419,53 @@

private async Task OnSearchButtonClick()
{
if (GridRef != null)
if (GridRef is null)
{
var gridState = GridRef.GetState();
return;
}

var searchString = $"{(char)Random.Shared.Next(97, 123)}{(char)Random.Shared.Next(97, 123)}";
GridState<GridModel> gridState = GridRef.GetState();

var cfd = new CompositeFilterDescriptor();
string searchString = $"{(char)Random.Shared.Next(97, 123)}{(char)Random.Shared.Next(97, 123)}";

cfd.LogicalOperator = FilterCompositionLogicalOperator.Or;
cfd.FilterDescriptors = new FilterDescriptorCollection();
CompositeFilterDescriptor cfd = new();

// Add one FilterDesccriptor for each string column
cfd.FilterDescriptors.Add(new FilterDescriptor()
{
Member = nameof(GridModel.Name),
MemberType = typeof(string),
Operator = FilterOperator.Contains,
Value = searchString
});
cfd.FilterDescriptors.Add(new FilterDescriptor()
{
Member = nameof(GridModel.Description),
MemberType = typeof(string),
Operator = FilterOperator.Contains,
Value = searchString
});
cfd.LogicalOperator = FilterCompositionLogicalOperator.Or;
cfd.FilterDescriptors = new FilterDescriptorCollection();

gridState.SearchFilter = cfd;
// Add one FilterDesccriptor for each string column
cfd.FilterDescriptors.Add(new FilterDescriptor()
{
Member = nameof(GridModel.Name),
MemberType = typeof(string),
Operator = FilterOperator.Contains,
Value = searchString
});
cfd.FilterDescriptors.Add(new FilterDescriptor()
{
Member = nameof(GridModel.Description),
MemberType = typeof(string),
Operator = FilterOperator.Contains,
Value = searchString
});

await GridRef.SetStateAsync(gridState);
}
gridState.SearchFilter = cfd;

await GridRef.SetStateAsync(gridState);
}

private async Task OnClearButtonClick()
{
if (GridRef != null)
if (GridRef is null)
{
var gridState = GridRef.GetState();
return;
}

(gridState.SearchFilter as CompositeFilterDescriptor)?.FilterDescriptors.Clear();
GridState<GridModel> gridState = GridRef.GetState();

await GridRef.SetStateAsync(gridState);
}
(gridState.SearchFilter as CompositeFilterDescriptor)?.FilterDescriptors.Clear();

await GridRef.SetStateAsync(gridState);
}

protected override void OnInitialized()
Expand Down
97 changes: 60 additions & 37 deletions components/grid/filter/searchbox.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,44 +12,68 @@ position: 20

In addition to [Grid filtering](slug:components/grid/filtering), you can enhance functionality by adding a SearchBox to the [Grid Toolbar](slug:components/grid/features/toolbar). This search box filters multiple Grid columns simultaneously.

Users type their query, and the Grid performs a case-insensitive Contains search on all visible string columns, adjusting the filters accordingly. To customize the filter delay and selected fields, see the [Customize the SearchBox section](#customize-the-searchbox).
Users type their query, and the Grid performs a case-insensitive Contains search on all visible string columns. To customize the filter delay and searchable columns, see the [Customize the SearchBox section](#customize-the-searchbox).

The SearchBox operates independently of Grid filtering, respecting existing filters and adding extra criteria to refine search results. To enable the SearchBox, include the `<GridSearchBox>` tag in the [`<GridToolBarTemplate>`](slug:components/grid/features/toolbar).
The SearchBox operates independently of Grid filtering, respecting existing filters and adding extra criteria to refine search results.

To enable the SearchBox, add the `<GridSearchBox>` tag in the [`<GridToolBarTemplate>`](slug:components/grid/features/toolbar).
## Basic Usage

To enable the built-in Grid SearchBox, use one of the following options:

* Add a `<GridToolBarSearchBoxTool>` tag to the [Grid ToolBar](slug:components/grid/features/toolbar). This approach is suitable if you are not using a Grid ToolBar yet, or if you are using only built-in ToolBar tools.
````RAZOR.skip-repl
<TelerikGrid>
<GridToolBar>
<GridToolBarSearchBoxTool />
</GridToolBar>
</TelerikGrid>
````

* Add a `<GridSearchBox>` tag to the [Grid ToolBar Template](slug:components/grid/features/toolbar#custom-toolbar-configuration). This approach is suitable if you have or need custom Grid ToolBar content.
````RAZOR.skip-repl
<TelerikGrid>
<GridToolBarTemplate>
<GridSearchBox />
</GridToolBarTemplate>
</TelerikGrid>
````

The following example shows the first option in action, while the [customization demo](#customize-the-searchbox) below uses a `GridToolBarTemplate`.

>caption Grid SearchBox

````RAZOR
<TelerikGrid Data="@GridData"
Pageable="true"
Sortable="true">
<GridToolBarTemplate>
<GridSearchBox />
</GridToolBarTemplate>
Height="90vh"
Pageable="true">
<GridToolBar>
<GridToolBarSearchBoxTool Placeholder="Type a letter or digit..." Width="180px" />
</GridToolBar>
<GridColumns>
<GridColumn Field="@nameof(SampleModel.Name)" />
<GridColumn Field="@nameof(SampleModel.Description)" />
<GridColumn Field="@nameof(GridModel.Id)" />
<GridColumn Field="@nameof(GridModel.Name)" />
<GridColumn Field="@nameof(GridModel.Description)" />
</GridColumns>
</TelerikGrid>

@code {
private List<SampleModel> GridData { get; set; } = new();
private List<GridModel> GridData { get; set; } = new();

protected override void OnInitialized()
{
for (int i = 1; i <= 50; i++)
Random rnd = Random.Shared;
for (int i = 1; i <= 1000; i++)
{
GridData.Add(new SampleModel()
GridData.Add(new GridModel()
{
Id = i,
Name = $"{(char)(64 + i % 26 + 1)}{(char)(64 + i % 26 + 1)} {i}",
Description = $"{(char)(123 - i % 26 - 1)}{(char)(123 - i % 26 - 1)} {i}"
Name = $"{(char)rnd.Next(65, 91)}{(char)rnd.Next(65, 91)} {rnd.Next(10, 100)}",
Description = $"{(char)rnd.Next(97, 123)}{(char)rnd.Next(97, 123)} {rnd.Next(10, 100)}"
});
}
}

public class SampleModel
public class GridModel
{
public int Id { get; set; }
public string Name { get; set; } = string.Empty;
Expand All @@ -58,7 +82,6 @@ To enable the SearchBox, add the `<GridSearchBox>` tag in the [`<GridToolBarTemp
}
````


## Search From Code

You can set or remove the search filters programmatically through the `SearchFilter` property of the [Grid state](slug:grid-state).
Expand All @@ -73,37 +96,36 @@ You can set or remove the search filters programmatically through the `SearchFil

## Customize the SearchBox

The `GridSearchBox` component offers the following parameters to customize its behavior:
The [`GridToolBarSearchBoxTool`](slug:telerik.blazor.components.gridtoolbarsearchboxtool) and [`GridSearchBox`](slug:telerik.blazor.components.gridsearchbox) components offer the same variety of parameters to customize its behavior.

@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
`DebounceDelay` sets the time in milliseconds between the user typing ends and the search starts. This provides a performance optimization when using the [`OnRead` event](slug:common-features-data-binding-onread). Filtering does not occur on every keystroke during fast typing, unless `DebounceDelay` is set to `0`.

| Parameter | Type and Default&nbsp;Value | Description |
| --- | --- | --- |
| `Class` | `string`| The custom CSS class that renders on the SearchBox wrapper (`<span class="k-searchbox">`). |
| `DebounceDelay` | `int` <br /> (`300`) | The time in milliseconds between the user typing ends and the search starts. This provides a performance optimization when using the [`OnRead` event](slug:common-features-data-binding-onread). Filtering does not occur on every keystroke during fast typing, unless `DebounceDelay` is set to `0`. |
| `Fields` | `List<string>` | The collection of model properties to search in. By default, the Grid searches in all visible columns that are bound to `string` fields. You can only define a subset of those fields. It is also possible to programmatically [search in `string` fields, which are not displayed in the Grid](slug:grid-kb-search-in-hidden-fields). |
| `Placeholder` | `string` <br /> (`"Search..."`) | The textbox placeholder that hints the user what the SearchBox does. The built-in default value is [localized](slug:globalization-localization). |
| `Width` | `string` | Specifies the width of the SearchBox component. |
The Grid searches in all visible string columns or a subset of theirs. It is also possible to programmatically [search in `string` fields, which are not displayed in the Grid](slug:grid-kb-search-in-hidden-fields).

The example below demonstrates all SearchBox settings in action, and also how to move the SearchBox on the opposite side of the Grid toolbar.
The example below demonstrates all SearchBox settings in action, and also how to move the SearchBox on the opposite side of the Grid ToolBar when using `GridToolBarTemplate`.

>caption Grid SearchBox customizaton

````RAZOR
<TelerikGrid Data="@GridData"
Pageable="true"
Sortable="true">
PageSize="20"
Sortable="true"
Height="90vh">
<GridToolBarTemplate>
<span class="k-toolbar-spacer"></span>
<GridSearchBox Class="primary-searchbox"
DebounceDelay="300"
Fields="@SearchableFields"
FillMode="@ThemeConstants.SearchBox.FillMode.Outline"
Placeholder="Search Name Column..."
Rounded="@ThemeConstants.SearchBox.Rounded.Large"
Size="@ThemeConstants.SearchBox.Size.Small"
Width="240px" />
</GridToolBarTemplate>
<GridColumns>
<GridColumn Field="@nameof(SampleModel.Name)" />
<GridColumn Field="@nameof(SampleModel.Description)" />
<GridColumn Field="@nameof(GridModel.Name)" />
<GridColumn Field="@nameof(GridModel.Description)" />
</GridColumns>
</TelerikGrid>

Expand All @@ -114,24 +136,25 @@ The example below demonstrates all SearchBox settings in action, and also how to
</style>

@code {
private List<SampleModel> GridData { get; set; } = new();
private List<GridModel> GridData { get; set; } = new();

private List<string> SearchableFields = new List<string> { nameof(SampleModel.Name) };
private List<string> SearchableFields = new List<string> { nameof(GridModel.Name) };

protected override void OnInitialized()
{
for (int i = 1; i <= 50; i++)
Random rnd = Random.Shared;
for (int i = 1; i <= 1000; i++)
{
GridData.Add(new SampleModel()
GridData.Add(new GridModel()
{
Id = i,
Name = $"{(char)(64 + i % 26 + 1)}{(char)(64 + i % 26 + 1)} {i}",
Description = $"{(char)(123 - i % 26 - 1)}{(char)(123 - i % 26 - 1)} {i}"
Name = $"{(char)rnd.Next(65, 91)}{(char)rnd.Next(65, 91)} {rnd.Next(10, 100)}",
Description = $"{(char)rnd.Next(97, 123)}{(char)rnd.Next(97, 123)} {rnd.Next(10, 100)}"
});
}
}

public class SampleModel
public class GridModel
{
public int Id { get; set; }
public string Name { get; set; } = string.Empty;
Expand Down
2 changes: 1 addition & 1 deletion components/grid/toolbar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ The **Edit** command button is disabled if there is no [selected Grid row](slug:

| Tool Name | Tool Tag | Description |
| --- | --- | --- |
| Spacer | `GridToolBarSpacerTool` | Consumes the available empty space and pushes the rest of the tools next to one another. |
| Spacer | `GridToolBarSpacerTool` | Consumes the available empty space and pushes the rest of the tools next to one another. When using a [`GridToolBarTemplate`](#custom-toolbar-configuration), you can mimic this tool with `<span class="k-toolbar-spacer"></span>`. |

## Custom Tools

Expand Down