Our Blazor List Box component allows users to select items from a list of predefined strings. The component can be bound to any IEnumerable data source. The list of selected items can be accessed and/or specified via the Values property. To track selection changes, use the SelectedItemsChanged event or the two-way synchronization as demonstrated in this module.

In this demo, the component allows users to select a single item. Select an item to view corresponding object property values.

The List Box supports keyboard navigation (list of supported keyboard shortcuts), allowing users to navigate through List Box items and select values as needed.

To enable multiple selection in the List Box, set the SelectionMode property to ListBoxSelectionMode.Multiple.

• If the ShowCheckboxes option is enabled, users can click individual items and corresponding checkboxes or hold Shift to select a range of items.
• If the ShowCheckboxes option is disabled, users can press Ctrl to select individual items or hold Shift to select a range of items.

Set the ShowSearchBox property to true to display the search box in the List Box component. Once a user enters text in the search box, the List Box looks for the text in visible data column cells, filters, and highlights search results. The search is case-insensitive.

You can use the SearchText property to specify the search text in code. Handle the SearchTextChanged event to respond to search text changes. If the search text contains multiple words separated by space characters, 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 List Box control treats search words:

• GroupWordsByAnd — The control searches for individual words. A record must include all search words.
• GroupWordsByOr — The control searches for individual words. A record needs to include at least one word.
• ExactMatch — The control looks for exact matches of the entire search text.

For more information, refer to the following help topic: Search and Filter Data.

The DevExpress Blazor List Box allows you to filter data in code. To apply filter criteria, create a criteria operator object that specifies a filter expression and send this object to the SetFilterCriteria method. To obtain the applied filter criteria, use the GetFilterCriteria method.

When a filter is applied, the ListBox raises its FilterCriteriaChanged event.

You can call the ClearFilter method to clear previously applied filters and apply a new filter to List Box data.

For more information, refer to the following help topic: Filter Criteria.

The List Box can display data across multiple columns. To create columns, use DxListEditorColumn objects that include the following options for column customization:

• Caption — Specifies the column caption.
• FieldName — Specifies the data source field that populates column items.
• Visible — Specifies the column visibility.
• VisibleIndex — Specifies the column display order.
• Width — Specifies the column width.

To help you deliver the best possible user experience, our Blazor List Box allows you to organize its list items into groups.

Use the GroupFieldName property to group data within our Blazor List Box (Group field values appear as group headers the list).

Note the following when using this option:

• The List Box supports a single group level.
• Users cannot collapse groups.
• Group headers are not used for search operations.
• Multi-column List Box controls also support groups.
• You can use the GroupHeaderDisplayTemplate property to customize group headers.

Use the DisabledFieldName property to disable individual items within a List Box. The property specifies a Boolean field and stores each item's enabled or disabled state. Disabled items are grayed out and cannot be selected.

Note: Disabled items can improve overall usability but cannot replace appropriate security protocols (Users may still be able to select disabled items on the client side – as such, you should implement appropriate security-related checks in code).

The ListRenderMode property specifies how the List Box renders the item list.

• Entire — The List Box renders the entire item list. Use this option for small item lists where scrolling should be instantly.
• Virtual — The List Box renders items only after they appear in the viewport. This approach improves performance when the list contains many items.

In this demo, the ListRenderMode property is set to ListRenderMode.Virtual.

The List Box component provides access to item values. The value is assigned to the editor's value when a user selects an item from the list. To enable this access, set the ValueFieldName property to the name of the data source field that ships with values for the List Box items.

If the ValueFieldName property is not specified, the List Box component searches for a Value field in the data source and uses this field as a value field. Otherwise, values are not assigned to editor items.

To access values of the selected items, use the Values property. To track selection changes, use the ValuesChanged event or two-way synchronization as demonstrated in this module.

The ItemDisplayTemplate property allows you to customize the appearance of List Box items. The property accepts a ListBoxItemDisplayTemplateContext object as the context parameter. You can use the parameter's members to get information about items:

• DataItem
• DisplayText
• HighlightedDisplayText
• Value
• VisibleIndex

In this demo, the ItemDisplayTemplate property is used to display the ListBox's items in a card-like view. Each item shows an employee's first name, last name, photo, and phone number.

The ColumnCellDisplayTemplate property allows you to specify custom content and change the appearance of cells in ListBox columns. The property accepts a ListBoxColumnCellDisplayTemplateContext object as the context parameter. You can use the parameter's members to get information about columns:

• Column
• DataItem
• DisplayText
• HighlightedDisplayText
• Value
• VisibleIndex

This demo customizes the appearance of different columns.

The DevExpress Blazor ListBox displays an empty data area in the following cases:

• The Data property is unset.
• The specified data source does not contain items.
• You use the DataAsync property or the CustomData property to bind the List Box to a data source. The component sends the first request to a remote data source and waits for a response.

Define the EmptyDataAreaTemplate to customize content displayed in the empty data area. The template's context parameter includes the IsDataLoading property that allows you to determine whether the List Box data is still loading data.