Inputs

ListBox

Bit.BlazorUISelectListListboxMultiSelectList

The ListBox component is a list the user picks one item from, or several, that stays on the page rather than in a popup: a form input like Dropdown, without the dropdown, bound to Value or (with MultiSelect) Values and validated with its EditForm.

ForceAnimation (whole page)

Notes

The BitListBox is a Multi-API component which can accept the list of items in 3 different ways:
1. The BitListBoxItem class
2. A Custom Generic class, read through NameSelectors
3. The BitListBoxOption component

The list box is a WAI-ARIA listbox and a single tab stop: the arrow keys, Home, End and typing the start of a text move between the items. With one to choose, the selection follows the keyboard; with MultiSelect, Space (or Enter, or a click) adds an item to the selection or takes it out.

Usage

Every example is live. Open its code to see exactly what produced the component running underneath.

Basic

The items are given through Items, and the one the user picks is the Value. The Label names the list for everyone. Tab into the list and use the arrow keys, or type the first letters of a fruit.

Fruit

Value:

MultiSelect

With MultiSelect the user picks several items, which are the Values. The arrow keys only move; Space, Enter or a click adds the item to the selection or takes it out.

Fruits

Values:

Description & icon

An item can carry an icon before its text and a Description under it.

Shipping

Disabled

IsDisabled keeps the user off an item, which the keyboard passes by; Disabled keeps the user off the whole list.

Some disabled

Disabled

ReadOnly

A ReadOnly list box can be read and moved through with the keyboard, but its selection cannot be changed.

Read only

MaxHeight

MaxHeight is the height past which the list scrolls. The keyboard keeps the item it is on in view, and typing the start of a name goes straight to it.

Country

Value:

Validation

The list box binds to an EditForm and is validated with it, in both modes: ShowValidationMessage shows the messages of the field under the list. ErrorMessage and Invalid mark it invalid from the page itself.

Submitted:

With an error message

This fruit is out of season.

Events

OnSelectItem runs when an item is selected, and in multi select mode OnDeselectItem when one is taken out.

Last event:

External Icons

The Icon of an item takes the CSS classes of any icon library, such as FontAwesome or Bootstrap Icons.

FontAwesome

Bootstrap Icons

Style & Class

Style and Class reach the root, the Style and Class of an item reach that item, and Styles and Classes reach each part by name. The selected colors are also the public --bit-ListBox-* variables.

Style

Class

Item's Style & Class

Styles & Classes

RTL

Use BitListBox in right-to-left (RTL).

میوه

میوه‌ها

CSS variables

The public custom properties this component reads off its root, for what no parameter covers.

Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property: set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it, or on the Style of one instance to restyle it - and any instance nested inside it, which inherits the value too; a parameter changes one alone, as does the real CSS property on the instance's Style / Styles when that property does not inherit (opacity: 1 keeps one disabled instance undimmed without undimming a disabled one inside it), while an inherited one such as color or font-family also reaches the nested instances that do not set it themselves. Leave a variable unset and the component falls back to the theme token beside it.

BitListBox CSS variables

Name	Default value	Description
--bit-ListBox-selected-background	var(--bit-clr-bg-pri-active)	Background of a selected item.
--bit-ListBox-selected-color	var(--bit-clr-pri)	Color of the mark of a selected item: the bar of a single select one, the filled box of a multi select one.

API

Every parameter, public member, sub-class and enum this component exposes.

BitListBox parameters

Name	Type	Default value	Description
ChildContent	RenderFragment?	null	The content of the BitListBox, that are BitListBoxOption components.
Classes	BitListBoxClassStyles?	null	Custom CSS classes for the different parts of the list box.
DefaultValues	IEnumerable<TValue?>?	null	The values selected at first in multi select mode, when Values is not bound.
ErrorMessage	string?	null	A message saying what is wrong with the selection, shown under the list. Setting it marks the list box invalid.
Invalid	bool	false	Marks the list box invalid, with the same look and the same aria-invalid an ErrorMessage gives it.
Items	IEnumerable<TItem>	[]	The items of the list box.
Label	string?	null	The visible label of the list box, which is also what names it to a screen reader.
MaxHeight	string?	null	The height (any CSS length) past which the list scrolls.
MultiSelect	bool	false	Lets the user select several items, which are Values instead of Value.
NameSelectors	BitListBoxNameSelectors<TItem, TValue>?	null	The names (or selectors) of the members the items are read from, for items of a custom class.
OnDeselectItem	EventCallback<TItem>		The callback for when an item is taken out of the selection in multi select mode.
OnSelectItem	EventCallback<TItem>		The callback for when an item is selected (in multi select mode, added to the selection).
Options	RenderFragment?	null	Alias of ChildContent: the items declared as BitListBoxOption components.
ShowValidationMessage	bool	false	Shows the validation messages of the cascading EditContext for the list box under it, where ErrorMessage goes, while there is no ErrorMessage of the app's own.
Styles	BitListBoxClassStyles?	null	Custom CSS styles for the different parts of the list box.
Values	IEnumerable<TValue?>?	null	The values of the selected items in multi select mode. Two-way bindable.
ValuesExpression	Expression<Func<IEnumerable<TValue?>?>>?	null	The expression that identifies the bound Values, which ties the multi select mode to an EditContext. It is supplied by the compiler for a @bind-Values binding.

BitListBox public members

Name	Type	Default value	Description
FocusAsync	() => ValueTask		Moves the focus to the list box: to the item the keyboard is on, which is the selected one when it comes in.

BitComponentBase parameters

Name	Type	Default value	Description
AriaLabel	string?	null	Gets or sets the accessible label for the component, used by assistive technologies.
Class	string?	null	Gets or sets the CSS class name(s) to apply to the rendered element.
Dir	BitDir?	null	Gets or sets the text directionality for the component's content.
Disabled	bool	false	Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction.
ForceAnimation	bool	false	Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested.
HtmlAttributes	Dictionary<string, object>	new Dictionary<string, object>()	Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. An attribute written on the component wins over an entry of the same name.
Id	string?	null	Gets or sets the unique identifier for the component's root element.
Style	string?	null	Gets or sets the CSS style string to apply to the rendered element.
TabIndex	string?	null	Gets or sets the tab order index for the component when navigating with the keyboard.
Visibility	BitVisibility	BitVisibility.Visible	Gets or sets the visibility state (visible, hidden, or collapsed) of the component.

BitComponentBase public members

Name	Type	Default value	Description
UniqueId	Guid	Guid.NewGuid()	Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed.
RootElement	ElementReference		Gets the reference to the root HTML element associated with this component.

BitListBoxItem<TValue> properties

Name	Type	Default value	Description
AriaLabel	string?	null	The aria-label of the item, which replaces its text and description as what a screen reader names it by.
Class	string?	null	The custom CSS classes of the item.
Description	string?	null	A second line of text under the text of the item.
Icon	BitIconInfo?	null	The icon shown before the text of the item, using custom CSS classes for external icon libraries. Takes precedence over IconName.
IconName	string?	null	The name of the icon shown before the text of the item, from the built-in Fluent UI icons.
IsDisabled	bool	false	Whether the item is disabled: it cannot be selected, and the keyboard passes it by.
Key	string?	null	A unique value to use as the key of the item.
Style	string?	null	The custom CSS styles of the item.
Text	string?	null	The text of the item, which typeahead matches too.
Title	string?	null	The title (tooltip) of the item.
Value	TValue?	null	The value of the item: what selecting it writes to the Value (or adds to the Values) of the list box.

BitListBoxOption<TValue> properties

Name	Type	Default value	Description
AriaLabel	string?	null	The aria-label of the item, which replaces its text and description as what a screen reader names it by.
Class	string?	null	The custom CSS classes of the item.
Description	string?	null	A second line of text under the text of the item.
Icon	BitIconInfo?	null	The icon shown before the text of the item, using custom CSS classes for external icon libraries. Takes precedence over IconName.
IconName	string?	null	The name of the icon shown before the text of the item, from the built-in Fluent UI icons.
IsDisabled	bool	false	Whether the item is disabled: it cannot be selected, and the keyboard passes it by.
Key	string?	null	A unique value to use as the key of the item.
Style	string?	null	The custom CSS styles of the item.
Text	string?	null	The text of the item, which typeahead matches too.
Title	string?	null	The title (tooltip) of the item.
Value	TValue?	null	The value of the item: what selecting it writes to the Value (or adds to the Values) of the list box.

BitListBoxNameSelectors<TItem, TValue> properties

Name	Type	Default value	Description
AriaLabel	BitNameSelectorPair<TItem, string?>	new(nameof(BitListBoxItem<TValue>.AriaLabel))	The AriaLabel field name and selector of the custom input class.
Class	BitNameSelectorPair<TItem, string?>	new(nameof(BitListBoxItem<TValue>.Class))	The CSS Class field name and selector of the custom input class.
Description	BitNameSelectorPair<TItem, string?>	new(nameof(BitListBoxItem<TValue>.Description))	The Description field name and selector of the custom input class.
Icon	BitNameSelectorPair<TItem, BitIconInfo?>	new(nameof(BitListBoxItem<TValue>.Icon))	The Icon field name and selector of the custom input class.
IconName	BitNameSelectorPair<TItem, string?>	new(nameof(BitListBoxItem<TValue>.IconName))	The IconName field name and selector of the custom input class.
IsDisabled	BitNameSelectorPair<TItem, bool>	new(nameof(BitListBoxItem<TValue>.IsDisabled))	The IsDisabled field name and selector of the custom input class.
Key	BitNameSelectorPair<TItem, string?>	new(nameof(BitListBoxItem<TValue>.Key))	The Key field name and selector of the custom input class.
Style	BitNameSelectorPair<TItem, string?>	new(nameof(BitListBoxItem<TValue>.Style))	The CSS Style field name and selector of the custom input class.
Text	BitNameSelectorPair<TItem, string?>	new(nameof(BitListBoxItem<TValue>.Text))	The Text field name and selector of the custom input class.
Title	BitNameSelectorPair<TItem, string?>	new(nameof(BitListBoxItem<TValue>.Title))	The Title field name and selector of the custom input class.
Value	BitNameSelectorPair<TItem, TValue?>	new(nameof(BitListBoxItem<TValue>.Value))	The Value field name and selector of the custom input class.

BitNameSelectorPair properties

Name	Type	Default value	Description
Name	string		Custom class property name.
Selector	Func<TItem, TProp?>?		Custom class property selector.

BitListBoxClassStyles properties

Name	Type	Default value	Description
Root	string?	null	Custom CSS classes/styles for the root element of the BitListBox.
Label	string?	null	Custom CSS classes/styles for the label of the BitListBox.
List	string?	null	Custom CSS classes/styles for the list (the listbox element) of the BitListBox.
Item	string?	null	Custom CSS classes/styles for each item of the BitListBox.
SelectedItem	string?	null	Custom CSS classes/styles for each selected item of the BitListBox.
Check	string?	null	Custom CSS classes/styles for the check box of each item of a multi select BitListBox.
Icon	string?	null	Custom CSS classes/styles for the icon of each item of the BitListBox.
Text	string?	null	Custom CSS classes/styles for the text of each item of the BitListBox.
Description	string?	null	Custom CSS classes/styles for the description of each item of the BitListBox.
ErrorMessage	string?	null	Custom CSS classes/styles for the error message of the BitListBox.

BitVisibility enum

Name	Value	Description
Visible	0	The content of the component is visible.
Hidden	1	The content of the component is hidden, but the space it takes on the page remains (visibility:hidden).
Collapsed	2	The component is hidden (display:none).

BitDir enum

Name	Value	Description
Ltr	0	Ltr (left to right) is to be used for languages that are written from the left to the right (like English).
Rtl	1	Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic).
Auto	2	Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element.

Feedback

Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.

Open an issue

Start a discussion

Edit this page

View the component source

Edit the component