Skip to content
Primer Design System

Primer Design System

Select panel

Select panel is a semantic dialog that allows for complex selection options within an overlay.

On this page

On this page

Overview

The select panel allows users to choose one or multiple items from one or more lists and can include search functionality to speed up the selection. It can also be enhanced with additional form controls in the footer. For instance, the select panel is ideal for assigning individuals to tasks, adding labels to issues or pull requests, or switching to specific branches in a code repository.

Anatomy

Annotated image of select panel: The dialog box titled 'Apply labels' is depicted with various components. At the top, there are 'deselect all' and 'close' icon buttons, along with a search input. The main section displays a list of items with individual checkboxes, labeled as a role='listbox'. Towards the bottom, the footer contains an 'edit labels' button on the left, and on the right, there are 'cancel' and 'apply' buttons, annotated as declarative actions.

The select panel consists of three main areas:

  • Header: Always includes a title and a close button. An optional search/filter field can be added for quicker item finding. Once a selection is made, a "Deselect all" button should be visually present.
  • List (scrollable): Comprises action list items, supporting both single and multi-select options.
  • Footer: In multi-select scenarios, it includes "Cancel" and "Apply" buttons. If additional controls (like a checkbox or button) are needed, a footer is also required for single selections.

Options

The select panel provides both simple list-based single selection and complex multi-selection options, with features like filtering and link inclusion.

List (single select)

Two examples of single-select select panels are shown. The first example has a header titled 'Set label' with a close button and a search input. Below the header is a list of single-select items, and selecting an item closes the panel (indicated by a checkmark on the selected item). The footer contains an 'edit labels' button but no cancel and save buttons. The second example also features a header titled 'Set label' with a close button and a search input. The list below the header displays visual radio buttons to indicate that the select panel won't close upon making a selection. The footer contains a checkmark labeled 'Trigger workflows' and cancel and save buttons.

For single-item selection, if no consequential actions follow, the panel may close immediately, indicated by a checkmark on the selected item. However, when the selection triggers significant actions or the footer has additional elements (like a checkbox), declarative buttons are necessary. In such cases, the behavior is indicated visually by radio buttons, which allows users to confirm their choices, before submitting their selection.

For a simple list of pre-defined items without filtering or extra options/actions, consider using an action menu.

List (multi-select)

Two examples of a multi-select panel are showcased. The first example features a header labeled 'Set label' with a close button. Below that, there's a checkbox option labeled 'Select all' to quickly select all items. A list of items follows, each with an individual checkbox. Currently, the first item is selected, and the third item shows an indeterminate state on the checkbox, indicating its association with a bulk selection outside this panel. The footer contains an 'Edit label' button, along with cancel and save buttons. The save button is also labeled 'Apply (2)' to indicate the total selection.In the second example, the header has a 'Set label' title with a close button, and there's an additional 'Deselect all' button and a search input field below it. The list of items is similar to the first example, with the first item selected and the third item in an indeterminate state. The footer remains the same with an 'Edit labels' button, along with cancel and apply buttons.

Use the search feature to manage extensive lists. This approach helps to prevent potential performance issues, particularly since this component does not support virtualization.

The indeterminate selections feature is valuable for bulk actions on lists. For instance, if you have 20 selected items and some of them are tagged with different labels, an indeterminate checkbox (indicated by a horizontal line) appears for labels that are not uniformly applied to all items.

For static lists that don’t require search, the ”Select all” option at the top of the list allows for quick selection or deselection of all values.

Footer

The image shows multiple examples of select panel footers. The first example features an 'Edit labels' button, along with cancel and apply buttons. In the second example, there is a checkbox with a label 'Save for later,' accompanied by cancel and apply buttons. Moving on to the third example, it includes a 'View all labels' link, along with cancel and apply buttons. In the fourth example, there is only a 'View all labels' link. Lastly, the last example consists of just an 'Edit labels' button.

The footer may contain links, buttons, or checkboxes for additional actions. Declarative buttons, such as "Cancel" and "Apply", are essential for multiple selections or single selections with additional elements in the footer.

Current selection

Demonstrating a multi-select panel. The header contains a 'Filter by author' label, a 'Deselect all' button, a close button, and a search input. Below the header is a list of items, with the first two items already selected, as indicated by checkboxes on the left of each item. These selected items are annotated as the current selection. In the footer, there is a checkbox labeled 'Exclude in results,' accompanied by cancel and apply buttons.

To effectively summarize the current selection, it's important to display the selected items at the beginning of the unfiltered list. However, this behavior should occur only after users clear the search input or close and reopen the select panel. It is crucial to avoid the immediate reordering of items after selection to prevent disorienting and confusing users.

Error/Warning

Three examples of select panels with error or warning messages are depicted. In all examples, the header features a title 'Filter by author,' a close button, and a search input. The footer includes cancel and apply buttons. The first example displays an empty input field with a message instead of the list. The message has a title 'We couldn't load the authors' and a description 'Try again, or if the problem persists, contact support.'. In the second example, there is a value in the input field, but an error message is shown above the list of items. The error message reads 'We couldn't load the authors. Try again, or if the problem persists, contact support.' The error message has a light red background, a red warning icon, and red text. Lastly, the third example is similar to the second example but with a warning message. The warning message has a light yellow background, a dark yellow warning icon, and dark yellow text.

Error or warning messages are crucial for communicating issues like loading failures or important information to the user.

Empty state

The image showcases two examples of select panels with empty states. In the first example, the header displays a title 'Filter by author,' along with a close button and a search input field containing the value 'banana.' Instead of the list, an empty state is shown, featuring a title 'No author found for banana' and a description 'Try a different search term.'. The second example includes a header with the title 'Filter by label,' a close button, and a search input field with no value. Similar to the first example, the list is replaced by an empty state with a title 'No labels found' and a description 'To filter by label, you can create your first label and assign it to an issue.'

Provide explanatory messages in cases of no results, whether due to unmatched search/filter inputs or the absence of data.

Limited selections

This image presents an example of a multi-select panel with a limitation on total selections. The header contains a title 'Set assignees' and a description 'Select up to 5 people,' along with a deselect all button, close button, and a search input field below. The description is annotated as 'Indicate the maximum.' Below the header, there is a warning footer displaying the message 'You've reached the max selection of 5 assignees.'. This warning message is annotated as 'reason (aria-live).' Below the warning message, there is a list of items where the first 5 items are selected, and the remaining items are disabled. The footer also includes a cancel and save button.

Inform users about any selection limitations beforehand. Upon reaching the maximum selection, display a warning message, potentially with an upgrade link for paid features. The warning message is labeled with an aria-live attribute, ensuring that users with screen readers receive a notification when the message appears.

Loading

Loading states should be used to indicate ongoing processes at various stages, enhancing user awareness and interaction understanding.

The image showcases 4 examples of loading states that can appear in the select panel.In all examples, the header displays a title 'Assign people,' a close button, and a search input field. Additionally, each example includes a footer with a cancel and save button. The first example replaces the list with a spinner and a description below it stating 'Fetching people...'. In the second example, the list is replaced by a shimmering skeleton loader, indicating that items will appear there shortly. The third example shows a value in the input field, and the magnifying glass at the beginning of the input field is replaced by a spinner. The list displays previously loaded items. The last example contains no value in the input field, and one item is selected in the list. However, in this case, the apply button is replaced by a spinner enclosed within a rectangle of the same size as the previous apply button.
  1. Initial: Used during initial data retrieval to avoid displaying an empty list.
  2. Initial Skeleton: Used similarly for initial data retrieval, presenting a skeleton screen instead of an empty list.
  3. Searching/Filtering: A minimal loading indicator is used during searches, allowing users to retain or continue their selections.
  4. Confirmation: Essential when updates aren't instant or when there's no error messaging for failures, using a confirmation button to indicate update progress.

Behavior

Opening

Various trigger examples are displayed. The first example showcases an icon button with a cog icon. The second example presents a button with the internal label 'Assignees: 2 people'. The third example features a button with the external label 'Assignees' and an internal button label stating '2 people'. Lastly, the image shows an action menu with two items: 'Set labels...' and 'Delete...'.

Select panels can be activated by regular buttons, icon buttos, or action menu items. Proper labeling is crucial for representing current selections, either internally (within the button) or externally (adjacent to the button). Focus will be placed on the first interactive element within the select panel.

When the select panel is activated through an action menu, it should be displayed as a centered dialog using the dialog property.

Closing

To close the select panel, pressing 'Esc', selecting a 'Cancel' option or clicking outside will close the dialog, and return focus to the trigger element without retaining or submitting any user input. Conversely, clicking 'Submit' or pressing 'Enter' while focused in the listbox will submit the user's input.

Appearance

Two examples of multi-select panels. The first panel is anchored to a Set labels button. When the button is clicked, the multi-select panel opens adjacent to the button, allowing the user to make selections. The second panel is displayed as a centered dialog. When triggered, it appears at the center of the screen, allowing users to interact with the multi-select options in a modal-like interface.

The select panel can appear as either an anchored or centered dialog, depending on the trigger source.

Responsive

On smaller viewports, the select panel adapts to a full-screen or bottom sheet dialog. Enhanced sizes of buttons and list items improve usability on touch devices.

Ensure any additional action in the footer fits within a 320px viewport.
On a mobile device, a multi-select panel is presented as a full-screen dialog. In the header, the search input is labeled as 'Search.' The first item in the list is annotated as 'Action list item (medium).' The entire list is labeled as role='listbox'. The footer is annotated as 'Declarative action (medium),' signifying that the elements are larger on mobile devices to ensure more comfortable interactions.

See the Dialog guidelines for more details.

Usage guidelines

Predictability

Ensure clarity in the multi-selection process by using confirmatory actions. Avoid automatic updates or dialog closure upon selection.

Do
This multi select panel features a title, close button, and a search input. The first four items are selected, and the footer includes a cancel and apply button.

For multi selection have the user confirm their selection.

Don’t
This multi select panel features a title, close button and search input. However, in this case, the first four items are selected, but the footer with a cancel and apply button is missing.

Don't force users to submit their multi-selection by closing the dialog or auto-updating their choices upon selection.

Search/Filtering

Include a search or filter input for efficiency. Presenting a limited number of items, like frequently used labels, can optimize the selection process.

Do
A select panel is shown with a search input inside the header.

Always keep the search/filter input in the sticky header.

Don’t
A select panel is shown with a search input positioned between the header and list items, instead of being part of the header.

Don’t place the search/filter input in the scrollable area.

To enhance the performance and user experience, a smart approach involves returning a limited, chosen set of items. For example, displaying the most commonly used labels rather than the first 20 in alphabetical order can speed up the selection process and may even reduce the need for searching.

Do
A select panel is presented with a list of items ordered based on their frequency of use.

Order the items based on frequency of use.

Don’t
A select panel is presented with a list of items grouped based on their frequency of use. In this case the first group is called 'suggestions' and the second group 'all'.

Don’t add frequently used items in a separate group.

Distinction

Include only essential details to aid in item differentiation. Avoid unnecessary information that doesn't contribute to the selection process.

Do
A select panel, featuring a list of repositories. Each item in the list is uniquely represented by an avatar and a corresponding name.

Add info that can help differentiate items from each other.

Don’t
A select panel, featuring a list of repositories. Each item in the list is represented by the same repository icon.

Avoid repetitive info that can be assumed from it's context. In this instance, repository icons in a list of only repositories.

Items marked with a checkmark icon, unlike those with radio buttons or checkboxes, signal that the selection panel will close automatically after a choice is made.

Do
A single select panel is displayed, featuring a list of repositories. The current selection is visually indicated by a checkmark positioned on the left side of the selected item. This checkmark signifies that clicking on any of the items will automatically close the select panel. As a result, the footer with the cancel and apply buttons is not included in this particular select panel.

Use a checkmark icon to indicate that the single select panel will close when clicking an individual item.

Don’t
A single select panel is presented, showcasing a list of repositories. The current selection is visually indicated by a checkmark on the left side of the selected item. This checkmark implies that clicking on any item will automatically close the select panel. Consequently, the footer with the cancel and save buttons should be omitted from this select panel.

Avoid combining declarative buttons with single select items that feature checkmark icons.

Adding a checkbox to the footer requires declarative buttons, and items should feature visual radio buttons. While not actual radio buttons semantically, this design effectively indicates that the selection process continues after a choice is made.

Do
A single select panel is presented, showcasing a list of repositories. The current selection is visually indicated by an active radio button on the left side of the item. This indicates that clicking on any item will not close the select panel immediately, allowing the user to access the 'Open in a new tab' checkbox in the footer. The footer also includes a cancel and save button.

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.

Don’t
A single select panel is displayed, featuring a list of repositories. The current selection is indicated by a checkmark on the left side of the selected item. Clicking on any item will close the select panel, which might lead to accidental closure before accessing the 'Open in a new tab' checkbox in the footer. The footer also includes a cancel and save button.

Avoid mixing declaritive buttons and items with checkmark icons.

Clearing

Two examples of select panels: In the first panel, titled 'Set labels,' the header includes a close button. Below the header, there is a checkmark that allows users to select or deselect all items at once. In the second example, with a title 'Assign people,' the header features a deselect all button, a close button, and a search input. The search input has a value and indicates its loading status through a spinner, replacing the magnifying glass icon at the beginning of the input. Additionally, a clear button is located at the end of the search input to remove the current input.

The select panel supports various data clearance methods:

  1. In single and multi-selection modes with a search/filter input, an x-circle-fill icon for quick clearing.
  2. For multi-selection with search, a 'deselect all' icon button in the header.
  3. In multi-selection without search, a header checkbox allows for one-click selection or deselection of all items.
Do
In the select panel, the search input contains the value 'six' and features a clear button at the end of the input.

Display a clear icon within the input to clear it's value.

Don’t
In the select panel, the search input has the value 'six,' but it is missing the clear button at the end of the input.

Don't forget to display a clear icon when the input has a value.

In multi-selections with search capabilities, a deselect all icon button is accessible for easy unselection as soon as one item is selected.

Do
A multi-select panel is displayed with a search input and one selected item. The mouse cursor is hovering over the deselect all button.

When one or more items are selected, display a deselect all button in the header to deselect the entire selection.

Don’t
A multi-select panel is shown with a search input and one selected item. However, the deselect all button is missing from the panel.

When one or more items are selected don't forget to display a deselect all button in the header.

Keyboard interactions

Activation (Trigger)

KeyDescription
EnterOpens the select panel.
SpaceOpens the select panel.

Select panel

KeyDescription
EnterSubmits 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.
TabMove focus forward between interactive controls and widgets within the dialog.
Shift + TabMove focus backward between interactive controls and widgets within the dialog.
ArrowDownMove 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.
ArrowUpNavigate backward through items in the listbox. If at the first item in the listbox, ArrowUp does nothing.
HomeMove focus to first item in listbox.
PageUpMove focus to first item in listbox.
EndMove focus to last item in listbox.
PageDownMove focus to last item in listbox.
EscClose dialog and clear any changed inputs.

Multi-select

KeyDescription
ArrowDownNavigate through the listbox items.
SpaceSelect an item in the listbox.

Single-select

KeyDescription
ArrowDownNavigate through listbox items. Selection follows focus.

Accessibility

For enhanced accessibility, it's important to use explicit saving mechanisms in the select panel. This includes incorporating "Apply" and "Cancel" buttons for both single- and multi-selection scenarios. These buttons provide clear, accessible actions for users to confirm or revoke their selections.

Automatic saving may be suitable for single selections that do not include additional form controls. In such cases, the selection process is straightforward and does not require further user confirmation, making it accessible and efficient. However, when the selection process involves additional steps or consequences, explicit saving mechanisms are crucial to ensure that all users, including those with accessibility needs, can confidently and accurately manage their selections.

Related components