# ListBox
**Also known as:** SelectList, Listbox, MultiSelectList
## Description
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.
## 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. |
| 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. |
## 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. |
| 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. |
## Enums
### 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. |
## Sub Classes
### 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. |
## CSS Variables
Public CSS custom properties read off the component's root. Set one on `:root` to restyle every instance, on any ancestor to restyle the ones inside it, or on the `Style` of one instance to restyle it and every instance nested inside it, which inherits the value too - a parameter changes one alone, as does the real CSS property on its `Style` / `Styles` when that property does not inherit (`opacity`); an inherited one (`color`, `font-family`) reaches the nested instances that do not set it themselves.
| 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. |
## Examples
Item
Custom
Option
\n**Basic**:
```razor
> basicItems =
[
new() { Text = "Apple", Value = "apple" },
new() { Text = "Banana", Value = "banana" },
new() { Text = "Cherry", Value = "cherry" },
new() { Text = "Grape", Value = "grape" },
new() { Text = "Orange", Value = "orange" }
];
```
\n**MultiSelect**:
```razor
? multiValues;
private readonly List> basicItems =
[
new() { Text = "Apple", Value = "apple" },
new() { Text = "Banana", Value = "banana" },
new() { Text = "Cherry", Value = "cherry" },
new() { Text = "Grape", Value = "grape" },
new() { Text = "Orange", Value = "orange" }
];
```
\n**Description & icon**:
```razor
```
```csharp
private readonly List> iconItems =
[
new() { Text = "Standard", Description = "3 to 5 days, free", IconName = BitIconName.Car, Value = "standard" },
new() { Text = "Express", Description = "Next day, $9.99", IconName = BitIconName.Airplane, Value = "express" },
new() { Text = "Pick up", Description = "From a store near you", IconName = BitIconName.Shop, Value = "pickup" }
];
```
\n**Disabled**:
```razor
```
```csharp
private readonly List> disabledItems =
[
new() { Text = "Apple", Value = "apple" },
new() { Text = "Banana", Value = "banana", IsDisabled = true },
new() { Text = "Cherry", Value = "cherry" },
new() { Text = "Grape", Value = "grape", IsDisabled = true },
new() { Text = "Orange", Value = "orange" }
];
private readonly List> basicItems =
[
new() { Text = "Apple", Value = "apple" },
new() { Text = "Banana", Value = "banana" },
new() { Text = "Cherry", Value = "cherry" },
new() { Text = "Grape", Value = "grape" },
new() { Text = "Orange", Value = "orange" }
];
```
\n**ReadOnly**:
```razor
```
```csharp
private readonly List> basicItems =
[
new() { Text = "Apple", Value = "apple" },
new() { Text = "Banana", Value = "banana" },
new() { Text = "Cherry", Value = "cherry" },
new() { Text = "Grape", Value = "grape" },
new() { Text = "Orange", Value = "orange" }
];
```
\n**MaxHeight**:
```razor
> countryItems =
[
.. new[]
{
"Argentina", "Australia", "Austria", "Belgium", "Brazil", "Canada", "Chile", "China", "Denmark", "Egypt",
"Finland", "France", "Germany", "Greece", "India", "Indonesia", "Iran", "Ireland", "Italy", "Japan",
"Mexico", "Netherlands", "Norway", "Poland", "Portugal", "Spain", "Sweden", "Turkey"
}.Select(name => new BitListBoxItem { Text = name, Value = name })
];
```
\n**Validation**:
```razor
Submit
```
```csharp
public class ListBoxValidationModel
{
[Required(ErrorMessage = "Pick a fruit.")]
public string? Fruit { get; set; }
[MinLength(2, ErrorMessage = "Pick at least two fruits.")]
public IEnumerable? Fruits { get; set; } = [];
public override string ToString() => $"{Fruit} / {string.Join(", ", Fruits ?? [])}";
}
private readonly ListBoxValidationModel validationModel = new();
private string? validationResult;
private readonly List> basicItems =
[
new() { Text = "Apple", Value = "apple" },
new() { Text = "Banana", Value = "banana" },
new() { Text = "Cherry", Value = "cherry" },
new() { Text = "Grape", Value = "grape" },
new() { Text = "Orange", Value = "orange" }
];
```
\n**Events**:
```razor
item) => eventsLog = $"Selected {item.Text}";
private void HandleOnDeselectItem(BitListBoxItem item) => eventsLog = $"Deselected {item.Text}";
private readonly List> basicItems =
[
new() { Text = "Apple", Value = "apple" },
new() { Text = "Banana", Value = "banana" },
new() { Text = "Cherry", Value = "cherry" },
new() { Text = "Grape", Value = "grape" },
new() { Text = "Orange", Value = "orange" }
];
```
\n**External Icons**:
```razor
```
```csharp
private readonly List> externalIconItems1 =
[
new() { Text = "Car", Icon = "fa-solid fa-car", Value = "car" },
new() { Text = "Train", Icon = BitIconInfo.Fa("solid train"), Value = "train" },
new() { Text = "Plane", Icon = BitIconInfo.Fa("solid plane"), Value = "plane" }
];
private readonly List> externalIconItems2 =
[
new() { Text = "Bike", Icon = BitIconInfo.Bi("bicycle"), Value = "bike" },
new() { Text = "Bus", Icon = BitIconInfo.Bi("bus-front"), Value = "bus" },
new() { Text = "Taxi", Icon = BitIconInfo.Bi("taxi-front"), Value = "taxi" }
];
```
\n**Style & Class**:
```razor
```
```csharp
private readonly List> styleClassItems =
[
new() { Text = "Apple", Value = "apple", Style = "color: seagreen;" },
new() { Text = "Banana", Value = "banana", Class = "custom-item" },
new() { Text = "Cherry", Value = "cherry" }
];
private readonly List> basicItems =
[
new() { Text = "Apple", Value = "apple" },
new() { Text = "Banana", Value = "banana" },
new() { Text = "Cherry", Value = "cherry" },
new() { Text = "Grape", Value = "grape" },
new() { Text = "Orange", Value = "orange" }
];
```
\n**RTL**:
```razor
```
```csharp
private readonly List> rtlItems =
[
new() { Text = "سیب", Value = "apple" },
new() { Text = "موز", Value = "banana" },
new() { Text = "گیلاس", Value = "cherry" }
];
```
Value: @basicValue
```
```csharp
private string? basicValue;
private readonly ListValues: @string.Join(", ", multiValues ?? [])
```
```csharp
private IEnumerableValue: @countryValue
```
```csharp
private string? countryValue;
private readonly ListSubmitted: @validationResult
Last event: @eventsLog
```
```csharp
private string? eventsLog;
private void HandleOnSelectItem(BitListBoxItem