Lists & dropdowns

DropDownListControl · DropDownGridControl · ListBoxControl

Let users pick from a list: a dropdown, a searchable lookup grid or checkboxes.

Overview

DropDownListControl is a Blazor dropdown that lets users pick one item from a list, or type an unlisted value when it is editable. Use DropDownGridControl instead when the list is long or needs columns, such as 4,009 airports searched by code or city, and ListBoxControl when every option should stay visible as radio buttons or checkboxes. All three take any item type.

Examples

#Pick two airports from a 4,009-row grid

Search 4,009 airports by code, city or country, pick two, and the page works out the distance between them. The boxes start on London Heathrow and Naples, the airport for the Amalfi trip below.

Flying from
Flying to

LHR → NAP: London Heathrow Airport, United Kingdom to Naples International Airport, Italy. Great-circle distance 1,630 km (1,013 miles).

#Choose several travelers

Check who is going to Amalfi in a Multiple list of two columns; Lead traveler lists only those and keeps one choice, and its switch sets ShowCheckbox, so a check box replaces each radio button and the choice can be cleared.

Who is going to Amalfi

Lead traveler

2 going: Albus Door, Hermione Ranger · Lead traveler: Hermione Ranger

Documentation

ParameterTypeDefaultDescription
DataSourceIEnumerable<TItem>?nullThe items. Enumerated again on each render for the options, the closed text and the automatic width. Null shows "No values" in the open list.
TextFieldName / ValueFieldNamestring""Names of the item properties that give each option its text and its value, read by reflection. Blank uses the item itself (a string) or its ToString().
ValueTValue?nullThe current value. A value that matches no option shows as its own text; null or an empty string counts as no value.
Placeholderstring?nullGray text in the closed button, or the input's placeholder, while there is no value. Also counts toward the automatic width.
AriaLabelstring?nullaria-label of the button or the editable input.
Widthstring?nullCSS width of the host. Unset: sized to the longest option text or the placeholder, 8 to 28 characters plus room for the arrow, never wider than the window less 24px.
PanelMaxHeightint180Tallest open list in pixels before it scrolls. The visible space around the box can make it shorter.
PanelFitContentWidthboolfalseSizes the open list to its widest option (at most 360px or 90% of the window) instead of the box width.
CssClassstring?nullAdded to the host and to the button (or the editable input's wrapper).
EnabledbooltrueFalse disables the button or input and closes an open list.
TabIndexint?nulltabindex of the button or input. Unset: the normal tab order, or -1 when the control is the editor of a hosted cell.
ItemTemplateRenderFragment<TItem>?nullContent of each option in the open list. The closed button and the editable input still show the TextFieldName text.
EditableboolfalseRenders a text input instead of the button. Typed text is committed on Enter (and on blur, see below) and converted to TValue, whether or not it is in the list.
MaxLengthint?nullmaxlength of the editable input; a committed typed text longer than this is cut to it.
CommitEditableTextOnBlurbooltrueEditable only: leaving the input commits the typed text. False commits on Enter only, and leaving a closed list puts back the committed text.
AutoFocusboolfalseFocuses the button or input after the first render.
OpenOnRenderboolfalseOpens the list on the first render where this is true, once.
OpenOnArrowClickOnlyboolfalseOnly a click on the arrow opens and closes the list; a click on the text does nothing.
OpenOnClickWhenClosedboolfalseWith OpenOnArrowClickOnly, a click on the text of a closed list still opens it; closing stays with the arrow, Escape, a pick or a click outside.
DelegateVerticalArrowsboolfalseUp and Down on a closed list go to OnKeyDown instead of changing the value. Needs an OnKeyDown handler.
SuppressUnchangedValueChangeboolfalsePicking the option that is already the value closes the list without raising ValueChanged or ValueChange.
AllowFilteringboolfalseDeclared but not read anywhere in the control: the list is never filtered.
ChildContentRenderFragment?nullDeclared but never rendered.

Option text and values are compared as strings: an option is the selected one when its value text equals Value.ToString() exactly, and a picked or typed text is converted back to TValue (strings as they are, enums by name ignoring case, other types with Convert.ChangeType in the invariant culture; text that does not convert gives default). The open list opens upward when it does not fit below the box and there is more room above.

An unhandled error has occurred. Reload 🗙

Rejoining the server...

Rejoin failed... trying again in seconds.

Failed to rejoin.
Please retry or reload the page.

The session has been paused by the server.

Failed to resume the session.
Please retry or reload the page.