Skip to content
Primer Design System
BrandView ComponentsReact Components

Select panel

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

On this page

On this page

Overview

Select panel is used for overlay containers that contain multiple control sets which includes advanced single or multi-selection with a filter. Select panel can be anchored to a trigger, or centered within a view.

Commonly, select panel is used for metadata application to an Issue or Pull Request, like assignee and label selections, or the branch selector on a repository’s code tab.

Anatomy

Select panel for assigning labels to an issue. 'Apply labels to this issue' heading, close button in upper right hand corner. Search input with a magnifer icon as a visible label, listbox of label options and the first three are selected with a visual checkbox. The footer contains a button to edit labels, and cancel and apply buttons. Purple labels are overlayed onto select panel: Overlay (dialog) pointing to the container, Search input pointing to the input, role='listbox' bracket of the listbox content, Optional action control to the button in the lower left corner, Explicit confirm / submission buttons bracket for the apply and cancel buttons in the lower right corner.

Options

First select panel is a branch switcher control that includes tabs, a search input, a listbox with single-select items, and a footer with an All branches link, and cancel and apply buttons. Second select panel is titled 'Show fields, with a list of about 10 multi-select items and apply and cancel buttons in the footer.

Select panel can have as much as the branch selector component, or as little as just a multi-selection list. If the contents request user input beyond a semantic menu(example: the context menu on comments in GitHub), it’s likely you need a select panel.

Additional control slot

Three cropped select panel footers each displaying a different option of a control in the bottom right left corner: Link, button, or checkbox input.

An optional control slot is available in the select panel’s bottom left corner. Avoid use if not absolutely necessary in order to avoid component and decision overwhelm.

Anchoring

Select panel should be anchored to its trigger.

Anchored select panel to a trigger.

Best practices

Be predictable

Do
Select panel with a back button, close button, Heading, subheading, five multiple choice options with three of them selected, and apply and cancel buttons.

If there are more than single options in a menu, have a user confirm their choices.

Don’t

Never force users to submit their multi-select options by closing the dialog or auto-updating their choices upon selection.

Click-to-dismiss behavior

Do
Mouse cursor indicating a clicking action on the apply button.

Guide users to save or cancel their selections to dismiss select panel to prevent confusion and data loss.

Don’t
Mouse cursor indicating a click action outside of the dialog.

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.

Behavior

Opening

Mouse cursor hovering over an icon button and a focused icon button with the space and enter keys visually below the icon button.

A select panel trigger should be a semantic button. Mouse users can click and keyboard users can open with space or enter.

First select panel has focus applied to the search input with a blue 2px border. Second SelectPanel has no visible focus ring as focus is brought to the H1 of the dialog.

Focus should be placed on the first interactive item within select panel.

Closing

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.

Responsive

Select panel can become a full screen dialog or a bottom sheet at narrow viewports. Support at 320px is required if the select panel is larger at wider viewports. See narrow-viewport placement in the Dialog guidelines for more details.

Keyboard navigation

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.

Example behavior

Keyboard interaction with a single-select select panel demonstrating selection following focus with navigation via the ArrowDown key.

Related components