Skip to main content
All docs
V24.2

Filter Row in Blazor TreeList

  • 19 minutes to read

Enable the ShowFilterRow option to activate a row that allows users to filter data. The TreeList component generates and configures cell editors for filter row cells based on associated column data types. When a user types into an editor, the TreeList creates a filter condition based on the editor value and applies this condition to the corresponding column.

<DxTreeList Data="@Data" KeyFieldName="Id" ParentKeyFieldName="ParentId" ShowFilterRow="true">
    @*...*@
</DxTreeList>

Blazor TreeList Filter Row

Run Demo: TreeList - Filter Row

Filter Tree Modes

Specify the FilterTreeMode property to set how the TreeList component displays filtered nodes:

EntireBranch

The TreeList component displays a node that meets the filter criteria and all its parent and child nodes, even if they do not meet the criteria.

Entire Branch Filter Tree Mode

Nodes

The TreeList component ignores parent-child relationships and displays all nodes that meet the filter criteria at one level. This mode improves overall performance when the TreeList is bound to a large remote data source.

Nodes Filter Tree Mode

ParentBranch

The TreeList component displays a node that meets the filter criteria and all its parent nodes, even if they do not meet the criteria.

Parent Branch Filter Tree Mode

When the FilterTreeMode property is set to Auto (default), the filter tree mode depends on the bound data source. When bound to the GridDevExtremeDataSource, the TreeList component switches to the Nodes mode to improve performance. In other data binding scenarios, the TreeList operates in ParentBranch mode.

The following example switches the TreeList component to the EntireBranch mode:

@inject EmployeeTaskService TaskService

<DxTreeList Data="@Data"
            KeyFieldName="Id"
            ParentKeyFieldName="ParentId"
            ShowFilterRow="true"
            FilterTreeMode="TreeListFilterTreeMode.EntireBranch" >
    <Columns>
        <DxTreeListDataColumn FieldName="Name" Caption="Task" Width="40%" />
        <DxTreeListDataColumn FieldName="EmployeeName"
                              FilterRowValue='"John"'
                              FilterRowOperatorType="TreeListFilterRowOperatorType.Contains" />
        <DxTreeListDataColumn FieldName="StartDate" MinWidth="100" />
        <DxTreeListDataColumn FieldName="DueDate" MinWidth="100" />
        <DxTreeListDataColumn FieldName="Progress" DisplayFormat="{0}%" />
    </Columns>
</DxTreeList>

@code {
    List<EmployeeTask> Data { get; set; }

    protected override void OnInitialized() {
        Data = TaskService.GenerateData();
    }
}

Run Demo: Filter Row View Example: Getting Started with TreeList

Filter Row Editor Settings

Declare an object that contains editor settings in the EditSettings property to customize the default editor or replace it with another editor. If the editor does not support the associated data type, the TreeList uses a read-only text box instead. The table below lists classes that define cell editor settings and the corresponding data types:

Editor Settings

Generated for Data Types

Supported Data Types

DxComboBoxSettings

Enum, Boolean

All data types

DxDateEditSettings

DateOnly, DateTime, DateTimeOffset

DateOnly, DateTime, DateTimeOffset

DxMaskedInputSettings

Never generated

Numeric, String, TimeSpan, TimeOnly,
DateTime, DateOnly, DateTimeOffset

DxMemoSettings

Never generated

String

DxSpinEditSettings

Numeric

Numeric

DxTextBoxSettings

String

String

DxTimeEditSettings

TimeOnly

TimeOnly, TimeSpan, DateTime

In the following code snippet, the Task column’s markup contains the DxTextBoxSettings object that customizes the automatically generated editor.

@inject EmployeeTaskService EmployeeTaskService

<DxTreeList Data="TreeListData" KeyFieldName="Id" ParentKeyFieldName="ParentId" ShowFilterRow="true">
    <Columns>
        <DxTreeListDataColumn FieldName="Name" Caption="Task" Width="40%">
            <EditSettings>
                <DxTextBoxSettings NullText="Type a search string" 
                                   ClearButtonDisplayMode="DataEditorClearButtonDisplayMode.Never" />
            </EditSettings>
        </DxTreeListDataColumn>
        <DxTreeListDataColumn FieldName="EmployeeName"  />
        <DxTreeListDataColumn FieldName="StartDate" />
        <DxTreeListDataColumn FieldName="DueDate" />
    </Columns>
</DxTreeList>

@code {
    List<EmployeeTask> TreeListData { get; set; }

    protected override void OnInitialized() {
        TreeListData = EmployeeTaskService.GenerateData();
    }
}

Modified Editors

At runtime, you can handle the CustomizeFilterRowEditor event to customize editors in the filter row.

Filter Row Operator Type and Initial Value

The TreeList applies the Contains filter operator to columns bound to the String data type; in other cases, the Equals operator is used. You can use a column’s FilterRowOperatorType property to explicitly specify the operator type. The filter row keeps the current operator type after a user clears the filter row editor’s value.

The FilterRowValue property allows you to specify the initial value in the filter row editor. If you define this property, you should also specify the FilterRowOperatorType property.

@inject EmployeeTaskService EmployeeTaskService

<DxTreeList Data="TreeListData" KeyFieldName="Id" ParentKeyFieldName="ParentId" ShowFilterRow="true">
    <Columns>
        <DxTreeListDataColumn FieldName="Name"
                              Caption="Task"
                              FilterRowValue='"Product"'
                              FilterRowOperatorType="TreeListFilterRowOperatorType.Contains" />
        <DxTreeListDataColumn FieldName="EmployeeName" />
        <DxTreeListDataColumn FieldName="StartDate" />
        <DxTreeListDataColumn FieldName="DueDate" />
    </Columns>
</DxTreeList>

@code {
    List<EmployeeTask> TreeListData { get; set; }

    protected override void OnInitialized() {
        TreeListData = EmployeeTaskService.GenerateData();
    }
}

Filter Row Cell Template

You can create templates for filter row cells. Template properties are available at the component and column levels.

Element Property
Component level template DxTreeList.DataColumnFilterRowCellTemplate
Data column’s template DxTreeListDataColumn.FilterRowCellTemplate
Command column’s template DxTreeListCommandColumn.FilterRowCellTemplate
Selection column’s template DxTreeListSelectionColumn.FilterRowCellTemplate

In the following code snippet, the Mass column declares FilterRowCellTemplate. The template contains a combobox editor that allows users to select a filter from a set of predefined criteria.

Blazor TreeList Filter Row Custom Editors

@using DevExpress.Data.Filtering
@inject SpaceObjectDataProvider SpaceObjectDataProvider

<DxTreeList Data="TreeListData" ChildrenFieldName="Satellites" ShowFilterRow="true">
    <Columns>
        <DxTreeListDataColumn FieldName="Name" />
        <DxTreeListDataColumn FieldName="TypeOfObject" Caption="Type" />
        <DxTreeListDataColumn FieldName="Mass10pow21kg" Caption="Mass, kg" DisplayFormat="N2">
            <HeaderCaptionTemplate>Mass, 10<sup>21</sup> &#215; kg</HeaderCaptionTemplate>
            <FilterRowCellTemplate>
                <DxComboBox @bind-Value="context.FilterCriteria"
                            Data="MassIntervals" ValueFieldName="Criteria" TextFieldName="DisplayText"
                            ClearButtonDisplayMode="DataEditorClearButtonDisplayMode.Auto" />
            </FilterRowCellTemplate>
        </DxTreeListDataColumn>
        <DxTreeListDataColumn FieldName="MeanRadiusInKM" Caption="Radius, km" DisplayFormat="N2" />
        <DxTreeListDataColumn FieldName="Volume10pow9KM3" DisplayFormat="N2">
            <HeaderCaptionTemplate>Volume, 10<sup>9</sup> &#215; km<sup>3</sup></HeaderCaptionTemplate>
        </DxTreeListDataColumn>
        <DxTreeListDataColumn FieldName="SurfaceGravity" DisplayFormat="N2">
            <HeaderCaptionTemplate>Gravity, m/s<sup>2</sup></HeaderCaptionTemplate>
        </DxTreeListDataColumn>
    </Columns>
</DxTreeList>

@code {
    object TreeListData { get; set; }
    static readonly IReadOnlyList<PriceFilterInterval> MassIntervals = new PriceFilterInterval[] {
        new("[Mass10pow21kg] < 100", "< 100"),
        new("[Mass10pow21kg] between (100, 10000)", "100 to 10 000"),
        new("[Mass10pow21kg] between (10000, 1000000)", "10 000 to 1 000 000"),
        new("[Mass10pow21kg] > 1000000", "> 1 000 000")
    };
    record PriceFilterInterval(CriteriaOperator Criteria, string DisplayText) {
        public PriceFilterInterval(string CriteriaText, string DisplayText)
            : this(CriteriaOperator.Parse(CriteriaText), DisplayText) {}
    }

    protected override async Task OnInitializedAsync() {
        TreeListData = SpaceObjectDataProvider.GenerateData();
    }
}

Command Column

Declare a DxTreeListCommandColumn object in the Columns template to display a command column. This column contains the Clear button that resets the entire filter. You can use the ClearFilterButtonVisible property to control button visibility.

You can also define the column’s FilterRowCellTemplate to display custom content in the filter row cell.

Blazor TreeList Filter Row Command Column

Disable Column Filtering

Disable a column’s FilterRowEditorVisible property to prevent users from filtering data by this column. The following example hides the filter row editor in the Surface Gravity column:

@inject SpaceObjectDataProvider SpaceObjectDataProvider

<DxTreeList Data="TreeListData" ChildrenFieldName="Satellites" ShowFilterRow="true">
    <Columns>
        <DxTreeListDataColumn FieldName="Name" />
        <DxTreeListDataColumn FieldName="TypeOfObject" Caption="Type" />
        <DxTreeListDataColumn FieldName="Mass10pow21kg" Caption="Mass, kg" DisplayFormat="N2">
            <HeaderCaptionTemplate>Mass, 10<sup>21</sup> &#215; kg</HeaderCaptionTemplate>
        </DxTreeListDataColumn>
        <DxTreeListDataColumn FieldName="MeanRadiusInKM" Caption="Radius, km" DisplayFormat="N2" />
        <DxTreeListDataColumn FieldName="Volume10pow9KM3" DisplayFormat="N2">
            <HeaderCaptionTemplate>Volume, 10<sup>9</sup> &#215; km<sup>3</sup></HeaderCaptionTemplate>
        </DxTreeListDataColumn>
        <DxTreeListDataColumn FieldName="SurfaceGravity" FilterRowEditorVisible="false" DisplayFormat="N2">
            <HeaderCaptionTemplate>Gravity, m/s<sup>2</sup></HeaderCaptionTemplate>
        </DxTreeListDataColumn>
    </Columns>
</DxTreeList>

@code {
    object TreeListData { get; set; }

    protected override async Task OnInitializedAsync() {
        TreeListData = SpaceObjectDataProvider.GenerateData();
    }
}

Customize Filter Row Appearance

Handle the CustomizeElement event to customize the filter row appearance. Compare the event argument’s e.ElementType property with the TreeListElementType.FilterRow value to determine whether the processed element is the filter row.

To customize individual filter row elements, use the following values for the e.ElementType property:

  • TreeListElementType.FilterCell
  • TreeListElementType.FilterCommandCell
  • TreeListElementType.FilterSelectionCell

Apply a Filter When a User Types Text

To filter data as a user types in the filter row, follow the steps below:

<DxTreeListDataColumn FieldName="Name" Caption="Task">
    <FilterRowCellTemplate>
        <DxTextBox Text="@((string)context.FilterRowValue)" BindValueMode=BindValueMode.OnInput
                   TextChanged="(string v) => context.FilterRowValue = v" />
    </FilterRowCellTemplate>
</DxTreeListDataColumn>