DxListBox<TData, TValue>.SearchText Property

Specifies the text that the List Box uses to filter and highlight data.

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.v24.1.dll

NuGet Package: DevExpress.Blazor

Declaration

[Parameter]
public string SearchText { get; set; }

Property Value

Type	Description
String	The search text.

Remarks

The List Box component allows you to search text, and filter and highlight search results. Use the SearchText property to specify the search text in code. Refer to Search Syntax.

Razor

<DxListBox TData=Person TValue=Person Data="Staff.DataSource"
            ShowCheckboxes="true"
            SearchText="Sa"
            SelectionMode="@ListBoxSelectionMode.Multiple">
    <Columns>
        <DxListEditorColumn FieldName="FirstName"></DxListEditorColumn>
        <DxListEditorColumn FieldName="LastName"></DxListEditorColumn>
        <DxListEditorColumn FieldName="Department"></DxListEditorColumn>
    </Columns>
</DxListBox>

StaffData

namespace StaffData {
    public static class Staff {
        private static readonly Lazy<List<Person>> dataSource = new Lazy<List<Person>>(() => {
            var dataSource = new List<Person>() {
                new Person() { Id= 0 , FirstName="John", LastName="Heart", Department=Department.Electronics },
                new Person() { Id= 1 , FirstName="Samantha", LastName="Bright", Department=Department.Motors },
                new Person() { Id= 2 , FirstName="Arthur", LastName="Miller", Department=Department.Software },
                new Person() { Id= 3 , FirstName="Robert", LastName="Reagan", Department=Department.Electronics },
                new Person() { Id= 4 , FirstName="Greta", LastName="Sims", Department=Department.Motors },
                new Person() { Id= 5 , FirstName="Brett", LastName="Wade", Department=Department.Software },
                new Person() { Id= 6 , FirstName="Sandra", LastName="Johnson", Department=Department.Electronics },
                new Person() { Id= 7 , FirstName="Edward", LastName="Holmes", Department=Department.Motors },
                new Person() { Id= 8 , FirstName="Barbara", LastName="Banks", Department=Department.Software },
                new Person() { Id= 9 , FirstName="Kevin", LastName="Carter", Department=Department.Electronics },
                new Person() { Id= 10, FirstName="Cynthia", LastName="Stanwick", Department=Department.Motors },
                new Person() { Id= 11, FirstName="Sam", LastName="Hill", Department=Department.Electronics }};
            return dataSource;
        });
        public static List<Person> DataSource { get { return dataSource.Value; } }
    }

    public class Person {
        public int Id { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public Department Department { get; set; }
        public string Text => $"{FirstName} {LastName} ({Department} Dept.)";
        public override bool Equals(object obj) {
            if (obj is Person typedObj) {
                return (this.Id == typedObj.Id) && (this.FirstName == typedObj.FirstName) && (this.LastName == typedObj.LastName)
                && (this.Department == typedObj.Department);
            }
            return base.Equals(obj);
        }
    }

    public enum Department { Motors, Electronics, Software }
}

You can set a column’s SearchEnabled property to false to exclude a specific column from search operations.

If the search text contains multiple words separated by space characters, the words can be treated as a single condition or individual conditions based on the SearchTextParseMode property value.

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 implements an external search box for the List Box and uses two-way data binding (@bind-SearchText).

Razor

<DxTextBox NullText="Type search text..."
           InputDelay="500"
           @bind-Text="@SearchText"
           BindValueMode="BindValueMode.OnInput"
           ClearButtonDisplayMode="DataEditorClearButtonDisplayMode.Auto">
</DxTextBox>
<br />
<DxListBox TData=Person TValue=Person Data="Staff.DataSource"
            ShowCheckboxes="true"
            @bind-SearchText="@SearchText"
            SelectionMode="@ListBoxSelectionMode.Multiple">
    <Columns>
        <DxListEditorColumn FieldName="FirstName"></DxListEditorColumn>
        <DxListEditorColumn FieldName="LastName"></DxListEditorColumn>
        <DxListEditorColumn FieldName="Department"></DxListEditorColumn>
    </Columns>
</DxListBox>

@code{
    public string SearchText { get; set; }
}

StaffData

namespace StaffData {
    public static class Staff {
        private static readonly Lazy<List<Person>> dataSource = new Lazy<List<Person>>(() => {
            var dataSource = new List<Person>() {
                new Person() { Id= 0 , FirstName="John", LastName="Heart", Department=Department.Electronics },
                new Person() { Id= 1 , FirstName="Samantha", LastName="Bright", Department=Department.Motors },
                new Person() { Id= 2 , FirstName="Arthur", LastName="Miller", Department=Department.Software },
                new Person() { Id= 3 , FirstName="Robert", LastName="Reagan", Department=Department.Electronics },
                new Person() { Id= 4 , FirstName="Greta", LastName="Sims", Department=Department.Motors },
                new Person() { Id= 5 , FirstName="Brett", LastName="Wade", Department=Department.Software },
                new Person() { Id= 6 , FirstName="Sandra", LastName="Johnson", Department=Department.Electronics },
                new Person() { Id= 7 , FirstName="Edward", LastName="Holmes", Department=Department.Motors },
                new Person() { Id= 8 , FirstName="Barbara", LastName="Banks", Department=Department.Software },
                new Person() { Id= 9 , FirstName="Kevin", LastName="Carter", Department=Department.Electronics },
                new Person() { Id= 10, FirstName="Cynthia", LastName="Stanwick", Department=Department.Motors },
                new Person() { Id= 11, FirstName="Sam", LastName="Hill", Department=Department.Electronics }};
            return dataSource;
        });
        public static List<Person> DataSource { get { return dataSource.Value; } }
    }

    public class Person {
        public int Id { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public Department Department { get; set; }
        public string Text => $"{FirstName} {LastName} ({Department} Dept.)";
        public override bool Equals(object obj) {
            if (obj is Person typedObj) {
                return (this.Id == typedObj.Id) && (this.FirstName == typedObj.FirstName) && (this.LastName == typedObj.LastName)
                && (this.Department == typedObj.Department);
            }
            return base.Equals(obj);
        }
    }

    public enum Department { Motors, Electronics, Software }
}

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 List Box component can 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 List Box 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 a 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 List Box 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

Implements

DevExpress.Blazor.IListBox<TData, TValue>.SearchText