Skip to main content


Shadow dwc-listbox
Java API

The ListBox component is a user interface element designed to display a scrollable list of objects and allows users to select single or multiple items from the list. Users can also interact with the ListBox with the arrow keys.


  1. User Role Assignment: In applications with user access control, administrators can use a ListBox to assign roles and permissions to users. Users are selected from a list, and the roles or permissions are assigned based on their selection. This ensures precise and controlled access to different features and data within the application.

  2. Project Task Assignment: In project management software, ListBox components are useful for assigning tasks to team members. Users can select tasks from a list and assign them to different team members. This simplifies task delegation and ensures that responsibilities are clearly defined within the team.

  3. Multi-Category Filtering: In a search application, users often need to filter search results based on multiple criteria. A ListBox can display various filter options, such as

  • Product features
  • Price ranges
  • Brands.

Users can select items from each filter category, allowing them to refine search results and find exactly what they're looking for.

  1. Content Categorization: In content management systems, ListBox components assist in categorizing articles, images, or files. Users can select one or more categories to associate with their content, making it easier to organize and search for content items in the system.


  1. : Constructs a new ListBox without a label.
  2. : Constructs a new ListBox with the specified label.
  3. : Constructs a new ListBox with the given label and a listener to handle item selection events.

Selection Options

By default, the list box is configured to allow selection of a single item at a time. However, this can be easily configured with a built-in method which allows users to select multiple items using the Shift key for contiguous entry selection and Control (Windows) or Command (Mac) key for separate, multiple item selection. Use the

function to change this property. True will enable multiple selection, false disables it.

Additionally, the arrow keys can be used to navigate the ListBox, and typing a letter key while the ListBox has focus will select the option that begins with that letter, or cycle through the options beginning with that letter should multiple options exist.

Show Code


Shadow Parts

These are the various parts of the shadow DOM for the ListBox component, which will be required when styling via CSS is desired.


CSS Properties

These are the various CSS properties that are used in the component, with a short description of their use.


Reflected Attributes

The reflected attributes of a component will be shown as attributes in the rendered HTML element for the component in the DOM. This means that styling can be applied using these attributes.



This component relies on the following components - see the related article for more detailed styling information:


Best Practices

To ensure an optimal user experience when using the ChoiceBox component, consider the following best practices:

  1. Prioritize Information Hierarchy: When using a ListBox, ensure that the items are organized in a logical and hierarchical order. Place the most important and commonly used options at the top of the list. This makes it easier for users to find what they need without excessive scrolling.

  2. Limit List Length: Avoid overwhelming users with an excessively long ListBox. If there are a large number of items to display, consider implementing pagination, search, or filtering options to help users locate items quickly. Alternatively, you can group items into categories to reduce list length.

  3. Clear and Descriptive Labels: Provide clear and descriptive labels for each item in the ListBox. Users should be able to understand the purpose of each option without ambiguity. Use concise and meaningful item labels.

  4. Multi-Selection Feedback: If your ListBox allows for multiple selections, provide visual or textual feedback indicating that multiple items can be selected from the list.

  5. Default Selection: Consider setting a default selection for the ListBox, especially if one option is more commonly used than others. This can streamline the user experience by pre-selecting the most likely choice.