Skip to content

Updated the UG Documentation for listbox #6923

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 15, 2025
Merged

Updated the UG Documentation for listbox #6923

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 24 additions & 25 deletions blazor/listbox/accessibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,20 +9,20 @@ documentation: ug

# Accessibility in Blazor ListBox Component

The Blazor ListBox component followed the accessibility guidelines and standards, including [ADA](https://www.ada.gov/), [Section 508](https://www.section508.gov/), [WCAG 2.2](https://www.w3.org/TR/WCAG22/) standards, and [WCAG roles](https://www.w3.org/TR/wai-aria/#roles) that are commonly used to evaluate accessibility.
The Blazor ListBox component followed the accessibility guidelines and standards, including [ADA](https://www.ada.gov/), [Section 508](https://www.section508.gov/), and [WCAG 2.2](https://www.w3.org/TR/WCAG22/). It also implements appropriate [WCAG roles](https://www.w3.org/TR/wai-aria/#roles) to support assistive technologies.

The accessibility compliance for the Blazor ListBox component is outlined below.
The following table summarizes the accessibility compliance of the Blazor ListBox component.

| Accessibility Criteria | Compatibility |
| -- | -- |
| [WCAG 2.2 Support](../common/accessibility#accessibility-standards) | <img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Yes"> |
| [Section 508 Support](../common/accessibility#accessibility-standards) | <img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Yes"> |
| [Screen Reader Support](../common/accessibility#screen-reader-support) | <img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Yes"> |
| [Right-To-Left Support](../common/accessibility#right-to-left-support) | <img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Yes"> |
| [Color Contrast](../common/accessibility#color-contrast) | <img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Yes"> |
| [Mobile Device Support](../common/accessibility#mobile-device-support) | <img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Yes"> |
| [Keyboard Navigation Support](../common/accessibility#keyboard-navigation-support) |<img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Yes"> |
| [Axe-core Accessibility Validation](../common/accessibility#ensuring-accessibility) | <img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Yes"> |
| [WCAG 2.2 Support](../common/accessibility#accessibility-standards) | <img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Meets requirement"> |
| [Section 508 Support](../common/accessibility#accessibility-standards) | <img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Meets requirement"> |
| [Screen Reader Support](../common/accessibility#screen-reader-support) | <img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Meets requirement"> |
| [Right-to-left support](../common/accessibility#right-to-left-support) | <img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Meets requirement"> |
| [Color Contrast](../common/accessibility#color-contrast) | <img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Meets requirement"> |
| [Mobile Device Support](../common/accessibility#mobile-device-support) | <img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Meets requirement"> |
| [Keyboard Navigation Support](../common/accessibility#keyboard-navigation-support) |<img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Meets requirement"> |
| [Axe-core Accessibility Validation](../common/accessibility#ensuring-accessibility) | <img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Meets requirement"> |

<style>
.post .post-content img {
Expand All @@ -31,44 +31,43 @@ The accessibility compliance for the Blazor ListBox component is outlined below.
}
</style>

<div><img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Yes"> - All features of the component meet the requirement.</div>
<div><img src="https://cdn.syncfusion.com/content/images/landing-page/yes.png" alt="Meets requirement"> - All features of the component meet the requirement.</div>

<div><img src="https://cdn.syncfusion.com/content/images/landing-page/intermediate.png" alt="Intermediate"> - Some features of the component do not meet the requirement.</div>
<div><img src="https://cdn.syncfusion.com/content/images/landing-page/intermediate.png" alt="Partially meets requirement"> - Some features of the component do not meet the requirement.</div>

<div><img src="https://cdn.syncfusion.com/content/images/landing-page/no.png" alt="No"> - The component does not meet the requirement.</div>
<div><img src="https://cdn.syncfusion.com/content/images/landing-page/no.png" alt="Does not meet requirement"> - The component does not meet the requirement.</div>

## WAI-ARIA attributes

The Blazor ListBox component followed the [WAI-ARIA](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/) patterns to meet the accessibility. The following ARIA attributes are used in the Blazor ListBox component:
The Blazor ListBox component follows the [WAI-ARIA listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/) to meet accessibility requirements. The following ARIA attributes are used in the Blazor ListBox component:

| Attributes | Purpose |
| --- | --- |
| `role` | Indicates the ListBox component wrapper element as `listbox`, the `UL` element as `presentation`, and its list item as `option`. |
| `role` | Indicates the ListBox component wrapper element as `listbox`, the `ul` element as `presentation`, and each list item as `option`. |
| `aria-label` | Provides an accessible name for the ListBox component. |
| `aria-multiselectable` | Applied to the element with the ListBox role, tells assistive technologies that the list supports multiple selection. The default value is true. |
| `aria-selected` | Applied to elements with role option that are visually styled as selected to inform assistive technologies that the options are selected. |
| `aria-multiselectable` | Applied to the element with the `listbox` role to indicate that multiple selection is supported. This is applied when multiple selection is enabled (default behavior). |
| `aria-selected` | Applied to elements with the `option` role that are visually styled as selected to inform assistive technologies that the options are selected. |

## Keyboard interaction

The Blazor ListBox component followed the [keyboard interaction](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/#keyboardinteraction) guideline, making it easy for people who use assistive technologies (AT) and those who completely rely on keyboard navigation. The following keyboard shortcuts are supported by the Blazor ListBox component.

The Blazor ListBox component follows the [keyboard interaction](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/#keyboardinteraction) guidelines, supporting users of assistive technologies and those who rely on keyboard navigation. The following keyboard shortcuts are supported by the Blazor ListBox component.
| Windows | Mac| Actions |
| --- | --- | --- |
| <kbd>↑</kbd> | <kbd>↑</kbd> | Moves focus to the previous option. |
| <kbd>↓</kbd> | <kbd>↓</kbd> | Moves focus to the next option. |
| <kbd>Home</kbd> | <kbd>Home</kbd> | Moves focus to first option. |
| <kbd>End</kbd> | <kbd>End</kbd> | Moves focus to last option. |
| <kbd>Space</kbd> | <kbd>Space</kbd> | Changes the selection state of the focused option. |
| <kbd>Home</kbd> | <kbd>Home</kbd> | Moves focus to the first option. |
| <kbd>End</kbd> | <kbd>End</kbd> | Moves focus to the last option. |
| <kbd>Space</kbd> | <kbd>Space</kbd> | Toggles the selection state of the focused option. |
| <kbd>Ctrl + A</kbd> | <kbd>⌘</kbd> + <kbd>A</kbd> | Selects all options in the list. |
| <kbd>Ctrl + Shift + Home</kbd> | <kbd>⌘</kbd> + <kbd>⇧</kbd> + <kbd>Home</kbd> | Selects the focused option and all options up to the first option. |
| <kbd>Ctrl + Shift + End</kbd> | <kbd>⌘</kbd> + <kbd>⇧</kbd> + <kbd>End</kbd> | Selects the focused option and all options down to the last option. |
| <kbd>Ctrl</kbd> + <kbd>↑</kbd> or <kbd>↓</kbd> | <kbd>⌘</kbd> + <kbd>↑</kbd> or <kbd>↓</kbd> | Press Ctrl key with up / down arrow or mouse to select multiple items. |
| <kbd>Ctrl</kbd> + <kbd>↑</kbd> or <kbd>↓</kbd> | <kbd>⌘</kbd> + <kbd>↑</kbd> or <kbd>↓</kbd> | Moves focus without changing the current selection. Use Ctrl/Cmd with mouse click to toggle individual items. |

## Ensuring accessibility

The Blazor ListBox component's accessibility levels are ensured through an [axe-core](https://www.nuget.org/packages/Deque.AxeCore.Playwright) with playwright tests.
The Blazor ListBox component's accessibility levels are validated using [axe-core](https://www.nuget.org/packages/Deque.AxeCore.Playwright) with Playwright tests.

The accessibility compliance of the Blazor ListBox component is shown in the following sample. Open the [sample](https://blazor.syncfusion.com/accessibility/listbox) in a new window to evaluate the accessibility of the Blazor ListBox component with accessibility tools.
The accessibility compliance of the Blazor ListBox component is demonstrated in the following sample. Open the [sample](https://blazor.syncfusion.com/accessibility/listbox) in a new window to evaluate the component with accessibility tools.

{% previewsample "https://ej2.syncfusion.com/accessibility/list-box.html" %}

Expand Down
33 changes: 16 additions & 17 deletions blazor/listbox/data-binding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,25 +9,25 @@ documentation: ug

# Data Binding in Blazor ListBox Component

The ListBox loads the data from local data sources using the [DataSource](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.SfListBox-2.html) property.
The ListBox loads data from local or remote sources using the [DataSource](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.SfListBox-2.html) property.

| Fields | Type | Description |
|------|------|-------------|
| [Text](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.FieldSettingsModel.html#Syncfusion_Blazor_DropDowns_FieldSettingsModel_Text) | `string` | Specifies the display text of each list item. |
| [Value](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.FieldSettingsModel.html#Syncfusion_Blazor_DropDowns_FieldSettingsModel_Value) | `string` | Specifies the hidden data value mapped to each list item that should contain a unique value. |
| [GroupBy](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.FieldSettingsModel.html#Syncfusion_Blazor_DropDowns_FieldSettingsModel_GroupBy) | `string` | Specifies the category under which the list item has to be grouped. |
| [IconCss](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.FieldSettingsModel.html#Syncfusion_Blazor_DropDowns_FieldSettingsModel_IconCss) | `string` | Specifies the iconCss class that needs to be mapped. |
| [HtmlAttributes](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.FieldSettingsModel.html#Syncfusion_Blazor_DropDowns_FieldSettingsModel_HtmlAttributes) | `string` | Allows additional attributes to configure the elements in various ways to meet the criteria. |
| [Text](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.FieldSettingsModel.html#Syncfusion_Blazor_DropDowns_FieldSettingsModel_Text) | `string` | Specifies the display text of each list item. |
| [Value](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.FieldSettingsModel.html#Syncfusion_Blazor_DropDowns_FieldSettingsModel_Value) | `string` | Specifies the hidden data value mapped to each list item and should be unique. |
| [GroupBy](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.FieldSettingsModel.html#Syncfusion_Blazor_DropDowns_FieldSettingsModel_GroupBy) | `string` | Specifies the category under which each list item is grouped. |
| [IconCss](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.FieldSettingsModel.html#Syncfusion_Blazor_DropDowns_FieldSettingsModel_IconCss) | `string` | Specifies the CSS class for an icon to display with the item. |
| [HtmlAttributes](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.FieldSettingsModel.html#Syncfusion_Blazor_DropDowns_FieldSettingsModel_HtmlAttributes) | `object` | Specifies additional HTML attributes to configure item elements. |

N> When binding complex data to the ListBox, fields should be mapped correctly. Otherwise, the selected item remains undefined.
N> When binding complex data to the ListBox, map fields correctly. If the mapping is incorrect, selection and value binding may not work as expected.

## Local Data

Local data can be represented by the following ways.
Local data can be provided in the following ways.

### Array of string

The ListBox has support to load array of primitive data such as strings or numbers. Here, both value and text field acts as same.
The ListBox supports arrays of primitive values such as strings or numbers. In this case, both the Text and Value fields resolve to the same value.

```cshtml
@using Syncfusion.Blazor.DropDowns
Expand All @@ -43,7 +43,7 @@ public string[] Games = new string[] { "Badminton", "Cricket", "Football", "Golf

The ListBox can generate its list items through an array of object data. For this, the appropriate columns should be mapped to the [Fields](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.SfListBox-2.html) property.

In the following example, `id` and `sports` column from complex data have been mapped to the `Value` field and `Text` field, respectively.
In the following example, the `Text` property is mapped to the Text field and the `Id` property is mapped to the Value field.

```cshtml
@using Syncfusion.Blazor.DropDowns
Expand Down Expand Up @@ -75,9 +75,9 @@ In the following example, `id` and `sports` column from complex data have been m

### Array of complex object

The ListBox can generate its list items through an array of complex data. For this, the appropriate columns should be mapped to the [Fields](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.SfListBox-2.html) property.
The ListBox can generate items from an array of complex objects. Map nested properties to the [Fields](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DropDowns.SfListBox-2.html) property as needed.

In the following example, `sports.Name` column from complex data have been mapped to the `Text` field.
In the following example, the `Sports.Name` property from the complex data is mapped to the Text field.

```cshtml
@using Syncfusion.Blazor.DropDowns
Expand Down Expand Up @@ -109,14 +109,13 @@ In the following example, `sports.Name` column from complex data have been mappe
}
```

![Binding Complex Items with Blazor ListBox](images/blazor-listbox-bind-complex-items.png)
![Blazor ListBox bound to complex objects with nested field mapping](images/blazor-listbox-bind-complex-items.png)

## Remote Data

The ListBox supports retrieval of data from remote data services with the help of [DataManager](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Data.SfDataManager.html).

The following sample displays the employee names from `Employee` table.
The ListBox supports retrieving data from remote services using the [DataManager](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Data.SfDataManager.html).

The following example displays customer IDs from the `Orders` table.
```csharp

@using Syncfusion.Blazor.DropDowns
Expand Down Expand Up @@ -147,4 +146,4 @@ The following sample displays the employee names from `Employee` table.

```

![Blazor ListBox with Data Binding](images/blazor-listbox-with-data-binding.png)
![Blazor ListBox bound to remote data using DataManager](images/blazor-listbox-with-data-binding.png)
Loading