DxFilterBuilder Class

A UI component that allows users to build complex filter criteria with various filter conditions combined by logical operators.

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.v25.1.dll

NuGet Package: DevExpress.Blazor

Declaration

public class DxFilterBuilder :
    DxComponentBase,
    IFilterBuilderFieldsOwner,
    INestedSettingsOwner,
    IDisposable

Remarks

The DevExpress Blazor Filter Builder (<DxFilterBuilder>) allows users to create complex filter criteria. The component builds filter expressions using our DevExpress Criteria Operator language. You can use DxFilterBuilder as a standalone component or connect it to any data-aware DevExpress Blazor control.

Important

The Filter Builder component is currently available as a community technology preview (CTP).

Run Demo: Filter Builder

Add a Filter Builder to a Project

Follow the steps below to add a Filter Builder component to an application:

1. Use a DevExpress Project Template to create a new Blazor Server or Blazor WebAssembly application. If you use a Microsoft project template or already have a Blazor project, configure your project to incorporate DevExpress Blazor components.
2. Add the following markup to a .razor file: <DxFilterBuilder>…</DxFilterBuilder>.
3. Populate the component with fields using DxFilterBuilderField objects.

API Reference

Refer to the following list for the component API reference: DxFilterBuilder Members.

Static Render Mode Specifics

Blazor Filter Builder does not support static render mode. Enable interactivity to use the component in your application. Refer to the following topic for more details: Enable Interactive Render Mode.

Fields

Use the DxFilterBuilder.Fields property to specify a collection of root fields. A DxFilterBuilderField object implements an individual field.

Use DxFilterBuilderField.FieldName and DxFilterBuilderField.Type properties to supply fields with data and generate relevant editors based on data field types.

You can declare fields one by one in Razor markup:

<DxFilterBuilder>
    <Fields>
        <DxFilterBuilderField FieldName="Name" Caption="Subject" Type="typeof(string)" />
        <DxFilterBuilderField FieldName="OwnerID" Caption="Assignee" Type="typeof(int)" />
        <DxFilterBuilderField FieldName="CreatedDate" Caption="Created" Type="typeof(DateTime)" />
        <DxFilterBuilderField FieldName="FixedDate" Caption="Fixed" Type="typeof(DateTime)" />
    </Fields>
</DxFilterBuilder>

or iterate through model class properties and define fields in a loop:

<DxFilterBuilder>
    <Fields>
        @foreach(var field in typeof(Invoice).GetProperties()){
            <DxFilterBuilderField FieldName="@field.Name" Type="@field.PropertyType" />
        }
    </Fields>
</DxFilterBuilder>

Hierarchical Fields

For complex data models, you can organize fields into a tree-like structure. Use DxFilterBuilderField.Fields properties to manage nested field collections.

<DxFilterBuilder>
    <Fields>
        @* ... *@
        <DxFilterBuilderField FieldName="SupplierId"
                              Caption="Supplier"
                              Type="@typeof(int)">
            <Fields>
                <DxFilterBuilderField FieldName="Supplier.CompanyName"
                                      Caption="Company Name"
                                      Type="@typeof(string)" />
                <DxFilterBuilderField FieldName="Supplier.ContactName"
                                      Caption="Contact Name"
                                      Type="@typeof(string)" />
            </Fields>
        </DxFilterBuilderField>
    </Fields>
</DxFilterBuilder>

Field Captions

The Filter Builder component allows you to customize field captions to be displayed in the tree (DxFilterBuilderField.Caption) and in the resulting filter criteria (DxFilterBuilderField.CaptionFullPath):

<DxFilterBuilder>
    <Fields>
        @* ... *@
        <DxFilterBuilderField FieldName="SupplierId" Caption="Supplier" Type="@typeof(int)">
            <Fields>
                <DxFilterBuilderField FieldName="Supplier.CompanyName"
                                      Caption="Company Name"
                                      CaptionFullPath="Supplier.Company Name"
                                      Type="@typeof(string)" />
                <DxFilterBuilderField FieldName="Supplier.ContactName"
                                      Caption="Contact Name"
                                      CaptionFullPath="Supplier.Contact Name"
                                      Type="@typeof(string)" />
            </Fields>
        </DxFilterBuilderField>
    </Fields>
</DxFilterBuilder>

Customize Value Editors

Blazor Filter Builder generates and configures value editors for individual fields based on associated data types. You can declare an object that contains editor settings in the DxFilterBuilderField.EditSettings property to customize the default editor or replace it with another editor.

The following code snippet applies a mask to the Total currency field and configures a ComboBox for the Status enum field:

<DxFilterBuilder>
    <Fields>
        <DxFilterBuilderField FieldName="Total" Type="typeof(decimal)">
            <EditSettings>
                <DxSpinEditSettings Mask="c0" DisplayFormat="c0" />
            </EditSettings>
        </DxFilterBuilderField>
        <DxFilterBuilderField FieldName="Status" Type="typeof(string)">
            <EditSettings>
                <DxComboBoxSettings Data="StatusList" />
            </EditSettings>
        </DxFilterBuilderField>
    </Fields>
</DxFilterBuilder>

@code {
    IEnumerable<string> StatusList = new List<string>() {
        "New",
        "Postponed",
        "Fixed",
        "Rejected"
    };
}

Configure a Lookup Editor for a Foreign Key

For foreign key fields, you can display user-friendly text instead of ID values. To display user-friendly text, place a DxComboBoxSettings object in a field’s EditSettings tag and specify the editor data source, value field name, and text field name.

The following code snippet uses DxComboBoxSettings to customize display values for the Supplier field:

Razor

<DxFilterBuilder>
    <Fields>
        <DxFilterBuilderField FieldName="SupplierId"
                              Caption="Supplier"
                              Type="@typeof(int)">
            <EditSettings>
                <DxComboBoxSettings Data="Suppliers"
                                    ValueFieldName="SupplierId"
                                    TextFieldName="CompanyName">
                </DxComboBoxSettings>
            </EditSettings>
            <Fields>
                <DxFilterBuilderField FieldName="Supplier.CompanyName"
                                      Caption="Company Name"
                                      CaptionFullPath="Supplier.Company Name"
                                      Type="@typeof(string)" />
                <DxFilterBuilderField FieldName="Supplier.ContactName"
                                      Caption="Contact Name"
                                      CaptionFullPath="Supplier.Contact Name"
                                      Type="@typeof(string)" />
            </Fields>
        </DxFilterBuilderField>
    </Fields>
</DxFilterBuilder>

Supplier.cs

public partial class Supplier {
    public Supplier() {
        Products = new HashSet<Product>();
    }
    public int SupplierId { get; set; }
    public string CompanyName { get; set; }
    public string ContactName { get; set; }
    public string ContactTitle { get; set; }
    public string Address { get; set; }
    public string City { get; set; }
    public string Region { get; set; }
    public string PostalCode { get; set; }
    public string Country { get; set; }
    public string Phone { get; set; }
    public string Fax { get; set; }
    public string HomePage { get; set; }
    public virtual ICollection<Product> Products { get; set; }
}

Connect The Filter Builder to a Data-Aware Component

You can connect the Blazor Filter Builder to data-aware DevExpress Blazor UI components that support CriteriaOperator syntax:

DxGrid

A component that displays data in a tabular format and allows users to edit, sort, group, filter, and otherwise shape data.

DxTreeList

A component that displays hierarchical data in a tabular format and allows users to edit, sort, filter, and otherwise shape data.

DxPivotTable

A Pivot Table component for multi-dimensional data analysis and cross-tab reporting.

DxListBox<TData, TValue>

A component that can connect to a data source and display a list of selectable items.

For two-way filter synchronization, use the @bind attribute for the DxFilterBuilder.FilterCriteria property:

Razor

<DxFilterBuilder @bind-FilterCriteria="FilterCriteria">
    <Fields>
        <DxFilterBuilderField FieldName="ProductName" Caption="Product Name" Type="@typeof(string)" />
        <DxFilterBuilderField FieldName="CategoryId" Caption="Category" Type="@typeof(int)">
            <EditSettings>
                <DxComboBoxSettings Data="Categories" ValueFieldName="CategoryId" TextFieldName="CategoryName" />
            </EditSettings>
        </DxFilterBuilderField>
        <DxFilterBuilderField FieldName="SupplierId" Caption="Supplier" Type="@typeof(int)">
            <EditSettings>
                <DxComboBoxSettings Data="Suppliers" ValueFieldName="SupplierId" TextFieldName="CompanyName">
                    <ItemDisplayTemplate>
                        @{
                            var item = (Supplier)context.DataItem;
                        }
                        @item.CompanyName (@item.ContactName)
                    </ItemDisplayTemplate>
                </DxComboBoxSettings>
            </EditSettings>
            <Fields>
                <DxFilterBuilderField FieldName="Supplier.CompanyName" Caption="Company Name" CaptionFullPath="Supplier.Company Name" Type="@typeof(string)" />
                <DxFilterBuilderField FieldName="Supplier.ContactName" Caption="Contact Name" CaptionFullPath="Supplier.Contact Name" Type="@typeof(string)" />
            </Fields>
        </DxFilterBuilderField>
        <DxFilterBuilderField FieldName="UnitPrice" Caption="Unit Price" Type="@typeof(int)" />
        <DxFilterBuilderField FieldName="UnitsInStock" Caption="Units in Stock" Type="@typeof(int)" />
        <DxFilterBuilderField FieldName="QuantityPerUnit" Caption="Quantity per Unit" Type="@typeof(int)" />
        <DxFilterBuilderField FieldName="Discontinued" Type="@typeof(bool)" />
    </Fields>
</DxFilterBuilder>

<div>
    <DxButton Text="Clear" Click="ClearFilterCriteria" RenderStyle="ButtonRenderStyle.Secondary"/>
    <DxButton Text="Apply" Click="ApplyFilterCriteria" />
</div>

<DxGrid @ref="Grid" Data="Data"
        PageSize="15"
        ColumnResizeMode="GridColumnResizeMode.NextColumn"
        TextWrapEnabled="false" VirtualScrollingEnabled="true"
        FilterCriteriaChanged="GridFilterCriteriaChanged"
        FilterMenuButtonDisplayMode="GridFilterMenuButtonDisplayMode.Always">
    <Columns>
        <DxGridDataColumn FieldName="ProductName" MinWidth="100" />
        <DxGridDataColumn FieldName="Category.CategoryName" Caption="Category" MinWidth="100" />
        <DxGridDataColumn FieldName="Supplier.CompanyName" Caption="Company Name" MinWidth="100" />
        <DxGridDataColumn FieldName="Supplier.ContactName" Caption="Contact Name" MinWidth="100" />
        <DxGridDataColumn FieldName="UnitPrice" DisplayFormat="c" Width="10%" />
        <DxGridDataColumn FieldName="UnitsInStock" Caption="Units in Stock" Width="10%" />
        <DxGridDataColumn FieldName="QuantityPerUnit" Caption="Quantity per Unit" Width="15%" MinWidth="80" />
        <DxGridDataColumn FieldName="Discontinued" Width="10%" MinWidth="90" />
    </Columns>
</DxGrid>

@code {
    IGrid Grid { get; set; }
    object Data { get; set; }
    CriteriaOperator FilterCriteria { get; set; } = CriteriaOperator.Parse("StartsWith([ProductName], 'C') And ([UnitPrice] < 50 Or [Discontinued] = true)");
    IEnumerable<Product> Products { get; set; }
    IEnumerable<Category> Categories { get; set; }
    IEnumerable<Supplier> Suppliers { get; set; }
    List<Category> SelectedCategories { get; set; } = [];
    protected override async Task OnInitializedAsync() {
        Suppliers = await NwindDataService.GetSuppliersAsync();
        Categories = await NwindDataService.GetCategoriesAsync();
        Products = await NwindDataService.GetProductsAsync();
        // ...
    }
    protected override void OnAfterRender(bool firstRender) {
        base.OnAfterRender(false);
        if (firstRender && Grid != null)
            ApplyFilterCriteria();
    }
    void ApplyFilterCriteria() {
        Grid.SetFilterCriteria(FilterCriteria);
    }
    void ClearFilterCriteria() {
        FilterCriteria = null;
        Grid.ClearFilter();
    }
    void GridFilterCriteriaChanged(GridFilterCriteriaChangedEventArgs args) {
        FilterCriteria = args.FilterCriteria;
    }
}

Product.cs

public partial class Product {
    public Product() {
        OrderDetails = new HashSet<OrderDetail>();
    }
    public int ProductId { get; set; }
    public string ProductName { get; set; }
    public int? SupplierId { get; set; }
    public int? CategoryId { get; set; }
    public string QuantityPerUnit { get; set; }
    public decimal? UnitPrice { get; set; }
    public short? UnitsInStock { get; set; }
    public short? UnitsOnOrder { get; set; }
    public short? ReorderLevel { get; set; }
    public bool Discontinued { get; set; }
    public bool InStock => !Discontinued;
    public virtual Category Category { get; set; }
    public virtual Supplier Supplier { get; set; }
    public virtual ICollection<OrderDetail> OrderDetails { get; set; }
}

Supplier.cs

public partial class Supplier {
    public Supplier() {
        Products = new HashSet<Product>();
    }
    public int SupplierId { get; set; }
    public string CompanyName { get; set; }
    public string ContactName { get; set; }
    public string ContactTitle { get; set; }
    public string Address { get; set; }
    public string City { get; set; }
    public string Region { get; set; }
    public string PostalCode { get; set; }
    public string Country { get; set; }
    public string Phone { get; set; }
    public string Fax { get; set; }
    public string HomePage { get; set; }
    public virtual ICollection<Product> Products { get; set; }
}

Category.cs

public partial class Category {
    public Category() {
        Products = new HashSet<Product>();
    }
    public int CategoryId { get; set; }
    public string CategoryName { get; set; }
    public string Description { get; set; }
    public byte[] Picture { get; set; }
    public virtual ICollection<Product> Products { get; set; }
}

Troubleshooting

If a Blazor application throws unexpected exceptions, refer to the following help topic: Troubleshooting.

Implements

IComponent

IHandleEvent

IHandleAfterRender

IDisposable

Inheritance

Object

ComponentBase

DxComponentBase

DxFilterBuilder