Select panel is a semantic dialog that allows for complex selection options within an overlay.
On this page
On this page
The select panel allows you to select one or multiple items from a list, and it can be enhanced with additional controls like a search input to expedite the selection process. It is often used to augment information of a wide variety of items.
For instance, you may encounter a select panel when you need to assign someone to a task or add labels to an issue or pull request. It can also be utilized to select a specific branch in a code repository.
It's important to understand the differences between the select panel and action menu. The primary distinction lies in the fact that an action menu lacks the ability to include additional form controls and automatically closes after making a selection. Therefore, if you require a filterable list or the capability to make multiple selections at once, the select panel is the appropriate choice.
The select panel is composed of three main areas: a header, a scrollable list, and an optional footer.
- Header: The header always includes a title and a close button. Additionally, it can have an optional search/filter field to find items quicker. When a selection is made, a "Deselect all" button should also be present visually within the input on the far right.
- List (scrollable): The scrollable list consists of action list items, which can be either single or multi-select options.
- Footer: For multi-select scenarios, the select panel should include a footer that incorporates a "Cancel" and an "Apply" button also refered to as declaritive actions. If any additional controls are required, such as an extra checkbox or button, a footer becomes necessary as well in single selections.
The select panel provides flexibility by offering both simple list-based single selection and multi-selection options. Additionally, it can become more sophisticated by incorporating advanced features such as filtering functionality and the inclusion of links.
Select panels can be activated by either a regular button, icon button or action menu item. If the button is intended to represent the current selection, it's crucial to have a label associated with it, either internally (within the button) or externally (adjacent to the button).
If your selection doesn't trigger a series of events upon submission and doesn't include a checkbox in the footer, you may consider not adding a cancel/save button. In this scenario, when a selection is made, the select panel will instantly close similar to a menu. This behavior is indicated by a checkmark on the selected item. For example switching a branch is easily reversible and doesn't pose any risk of sending notifications to other users.
However, if the select panel does cause a series of events upon selection or if the footer includes additional form elements like a checkbox, it becomes necessary to include cancel/save buttons. In such cases, the behavior is indicated visually by radio buttons, which allows users to confirm their choices, before submitting their selections. For example setting the wrong assignee on an pull request poses the risk of sending notifications to the wrong user therefore the cancel/save button is crucial.
The multi-select list allows you to choose multiple items from a list and has additional features like select all or indeterminate selections.
The select all option at the top of the list allows for quickly deselecting or selecting all values. However, when implementing search functionality, this option becomes unavailable.
We highly recommend utilizing the search functionality instead of retrieving extensive lists from our API endpoints to enable the select all feature. By doing so, you can avoid potential performance issues, especially considering that this component lacks virtualization capabilities.
The indeterminate selections option is useful for performing bulk actions on lists. For example, if you have 20 selected items, but some of them have different labels attached, an indeterminate checkbox (represented by a horizontal line) is shown for labels that are not set on all items.
The optional footer at the bottom could include a single link, button or checkbox to take additional actions.
In case of a multi selection or single selection with a checkbox in the footer we always recommend using a "Cancel" and "Apply" button
To provide a summary of the current selection, it is essential to display the selected items at the beginning of the unfiltered list. This behavior should only occur after users clear the search input or close and reopen the select panel. Avoiding the immediate reordering of items after selection is crucial to prevent disorienting and confusing the users.
Sometimes, we encounter situations where things don't work as expected, or we need to inform users about something important. There are various ways to handle these scenarios depending on the situation.
For instance, if the default values fail to load initially, we display an error placeholder to let the user know that something went wrong.
When the initial values are loaded and the user performs a search for new values, there may be instances where the search fails. In such cases, it is essential to ensure that the user can still make a selection without losing their current selection. Instead, we display an error message at the top of the list, notifying the user about the search failure while preserving their ability to continue with their selection process.
When no results are available, it is essential to offer users an explanation instead of leaving a blank space. There can be various reasons for the absence of results. It could be due to the search or filter input value not matching any available data, or it could be because the user has yet to generate any data to display.
In certain situations, we may need to restrict the number of items a user can select, either due to infrastructure limitations or limitations based on paid features. It is important to inform the user about this restriction before they begin making their selection. The description can be used effectively to communicate this limitation.
When the user reaches the maximum allowed number of selections, we need to display a warning message indicating that they have reached their limit. This can also be an opportunity to provide a link for upgrading their account if the restriction is related to a paid feature. It is worth noting that the warning message is labeled with an
aria-live attribute, ensuring that users with screen readers receive a notification when the message appears.
It is important to provide visual cues to the user when certain processes may take longer than expected. Loading states can be utilized at different stages of using this component to communicate this information effectively.
- Initial: Should be used when retrieving the initial data to prevent users from seeing an empty list.
- Initial (skeleton): Should be used when retrieving the initial data to prevent users from seeing an empty list.
- Searching/Filtering: When users perform a search to fetch new items, it is important to maintain their current selections or allow them to continue making selections. In this case, a more minimal loading state should be used to indicate ongoing activity.
- Confirmation: If your layout does not incorporate optimistic updates or lacks error messaging for failed updates, it is crucial to use a confirmation button as a loading state to clearly communicate the progress of the update.
By employing these loading states, users can have a better understanding of the process and remain informed throughout their interactions with the component.
For multi selection have the user confirm their selection.
Don't force users to submit their multi-selection by closing the dialog or auto-updating their choices upon selection.
Guide users to save or cancel their selections to dismiss select panel to prevent confusion and data loss.
Don’t allow a click-outside-to-dismiss behavior for select panel. Users may be used to closing and submitting the information. Doing so would result in a loss of their changes.
Including a search or filter input field not only accelerates the selection process for users but also prevents the need to burden the browser or API endpoints with returning extensive lists of items.
Always keep the search/filter input in the sticky header.
Don’t place the search/filter input in the scrollable area.
Adopting a smart approach of returning a limited number of items at a time can significantly enhance speed and potentially eliminate the necessity for searching altogether. For instance, instead of presenting the first 20 labels in alphabetical order, providing the most commonly used labels can be more effective. This strategic implementation optimizes the selection process and improves user experience.
Order the items based on frequency of use.
Don’t add frequently used items in a separate group.
Select panels are designed to be lightweight and should not be overloaded with excessive information. For instance, when using a user picker, it is often sufficient to include essential details such as the username, full name, and avatar. Less relevant information, such as the total number of followers or location, can be omitted as it is not as crucial for the selection process.
Add info that can help differentiate items from each other.
Avoid repetitive info that can be assumed from it's context. In this instance, repository icons in a list of only repositories.
Items accompanied by a checkmark icon, as opposed to radio buttons or checkboxes, indicate that the selection panel will automatically close upon making a choice. Therefore, they cannot be used in conjunction with declarative buttons.
Use a checkmark icon to indicate that the single select panel will close when clicking an individual item.
Avoid combining declarative buttons with single select items that feature checkmark icons.
When an additional checkbox is added to the footer, declarative buttons are required, and the items should be accompanied by visually resembling radio buttons. Although they are not technically radio buttons in terms of semantics, using visual radio buttons can effectively convey that the selection process is not yet complete even after making a choice.
When adding an additional checkbox in the footer, it is necessary to use declarative buttons and ensure that the items are accompanied by radio buttons.
Avoid mixing declaritive buttons and items with checkmark icons.
The select panel offers multiple methods for clearing data, depending on the context.
- For both single and multi-selection modes that include a search/filter input, an x-circle-fill icon appears as soon as the input has a value. This enables users to swiftly clear the input value when needed.
- In multi-selection mode, when at least one item is selected and search functionality is present, a deselect all icon button is provided in the header. This button allows users to deselect all items in the list with a single click.
- In multi-selection mode without search functionality, the header contains a checkbox that facilitates selecting or deselecting all items in the list in a single click.
Display a clear icon within the input to clear it's value.
Don't forget to display a clear icon when the input has a value.
For multi-selections with search functionality, a convenient deselect all icon button becomes available as soon as at least one item is selected.
When one or more items are selected, display a deselect all button in the header to deselect the entire selection.
When one or more items are selected don't forget to display a deselect all button in the header.
When the select panel is activated through an action menu, it should be displayed as a modal dialog. It should never be shown as a submenu.
When the select panel is triggered by an action menu, it should be presented as a modal dialog.
Avoid displaying the select panel as a non-modal submenu within an action menu.
The select panel can appear as an anchored dialog or centered dialog.
- Anchored dialog: When triggered by a button or icon button but never by an action menu.
- Centered dialog: When triggered by a button, icon button or action menu.
On smaller breakpoints the select panel should always appear as a modal dialog.
The select panel can be activated through a semantic button, providing mouse users with the ability to click on it, while keyboard users can activate it by pressing the space or enter key.
Additionally, the select panel can be triggered through an action menu. In this scenario, it is important for the action menu to promptly close as soon as the select panel is triggered.
Focus should be placed on the first interactive item within select panel.
Pressing esc, or selecting “cancel” should close the current dialog and enter focus to the previous trigger. It should not retain or submit any user input.
Selecting the submit button or pressing the enter key while focused in the listbox should submit any user input.
On smaller viewports, the select panel can be transformed into either a full-screen dialog or a bottom sheet dialog. To ensure usability on touch devices, the confirmation buttons and action list items are also increased to a medium size, ensuring a sufficiently large hit target.
When adding an extra action in the footer, it is important to ensure that it still fits within a 320px viewport.
See the Dialog guidelines for more details.
|Opens the select panel.
|Opens the select panel.
|Submits the information in the form when focused in the listbox. Activates buttons or links focused within the select panel. Does no action when focused in the search input.
|Move focus forward between interactive controls and widgets within the dialog.
|Shift + Tab
|Move focus backward between interactive controls and widgets within the dialog.
|Move focus from the input to the listbox. (Shift+Tab required to move from listbox to input. Navigate forward through items in the listbox. If focus is on the last item in the listbox, ArrowDown does nothing.
|Navigate backward through items in the listbox. If at the first item in the listbox, ArrowUp does nothing.
|Move focus to first item in listbox.
|Move focus to first item in listbox.
|Move focus to last item in listbox.
|Move focus to last item in listbox.
|Close dialog and clear any changed inputs.
|Navigate through the listbox items.
|Select an item in the listbox.
|Navigate through listbox items. Selection follows focus.
Keyboard interaction with a single-select select panel demonstrating selection following focus with navigation via the ArrowDown key.