Popover keyboard support - focus return
When the popover is closed, focus returns to the element that launched it.
Shopify Polaris · all subjects
components
322 notes in this subject, read out of this brain and free to use. This is page 4 of 6.
Popover web component name
The web component for Popover is named `s-popover`.
Popover example: With searchable listbox
Popovers can be used to help merchants browse, filter, and choose from a list of options.
Popover example: With lazy loaded list
Popovers can be used to present merchants with a list that dynamically loads more items on scroll or arrow down.
Popover example: With form components
Popovers can be used to present secondary input tasks on demand.
Popover example: With content and actions
Popovers can be used to present a combination of content, instructions, and actions in a panel for tasks that are of low or secondary importance to the current page. When used this way, popovers provide useful entry points to related features without overwhelming merchants.
Popover example: With action list
Popovers can be used with an action list to present a set of actions in a disclosable menu.
Popover content relationships best practice
Popovers should contain navigation or actions that share a relationship to each other.
Popover information hierarchy best practice
Popovers should be used for secondary or less important information and actions since they are hidden until merchants hit the trigger.
Popover positioning best practice
Popovers should always be positioned next to the button or other interface element that triggers them.
Popover purpose and usage
Popovers are small overlays that open on demand. They let merchants access additional content and actions without cluttering the page. They are used to surface secondary information or actions.
Popover action verb-led content guideline
Buttons in popovers should always lead with a strong verb that encourages action. Use the {verb}+{noun} format on buttons except in the case of common actions like Save, Close, Cancel, or OK. For example, use 'Rename', 'Edit HTML', or 'Duplicate' rather than 'HTML editing options', 'File name changes', or 'Duplicate this order so that you can make edits, updates, or changes'.
Popover action scannability content guideline
Popover actions should be scannable, especially when the popover contains a list of actions or options. Avoid unnecessary words and articles such as 'the', 'an', or 'a'. For example, use 'Add menu item' rather than 'Add a menu item'.
Popover navigation link conciseness guideline
If a popover includes a series of navigational links, each item should be concise but still give merchants enough information so they can easily find and accurately navigate to the path they want. For example, use 'Online store', 'Messenger', 'Facebook', or 'Buy Button' rather than 'Sales channel'.
Popover autofocusTarget for screen readers
To assist screen readers with sending focus to an action list, pass `autofocusTarget='first-node'` to `Popover`. This will avoid known issues a screen reader may have with keyboard support once focus is moved off the activator.
Choice list related components
To present a long list of radio buttons or when space is constrained, use the select component. To build a group of radio buttons or checkboxes with a custom layout, use the radio button component or checkbox component. To display a simple, non-interactive list of related content, use the list component.
Choice list purpose and usage
A choice list component lets you create a list of grouped radio buttons or checkboxes. Use this component when you need to group together a related list of interactive choices.
Choice list default behavior
The default choice list allows merchants to select one option from a list. All options should be an either/or choice.
Choice list multi-choice behavior
Choice lists can be configured to allow merchants to select multiple options from a list. When using multi-choice, avoid options that are an either/or choice.
Choice list with children content variants
Choice lists support two approaches for additional content under a choice: static children content that is always rendered, and dynamic children content that is only rendered when the choice is selected. Dynamic children content works for both single-choice and multi-choice lists.
Choice list best practices
Choice lists should include a title that tells merchants what to do or explains the available options. Options should be labeled clearly based on what the option will do. Avoid mutually exclusive options when allowing multiple selection.
Choice list title content guidelines
List titles should help merchants understand how the items in the list are grouped together or explain what kind of choice merchants are making. Titles should be kept to a single sentence, use simple and clear language that can be read at a glance, be written in sentence case, and if the title introduces the list, it should end with a colon.
Choice list choice item content guidelines
Every item in a choice list should start with a capital letter, not use commas or semicolons at the end of each line, and be written in sentence case with the first word capitalized and the rest lowercase.
Choice list helper text and descriptions punctuation
If your choice list contains helper text, only the description below the list item should contain punctuation.
Choice list accessibility
The choice list component uses the accessibility features of the checkbox and radio button components.
Choice list web component
The web component name is s-choice-list. Documentation is available at https://shopify.dev/docs/api/app-home/polaris-web-components/forms/choicelist
Choice list examples available
Available example files include: choice-list-default.tsx (default single-choice), choice-list-with-error.tsx (accessible error handling), choice-list-with-multi-choice.tsx (multiple selection), choice-list-with-children-content.tsx (always rendered additional content), and choice-list-with-dynamic-children-content.tsx (conditionally rendered additional content).
Combobox anatomy and composition
A combobox is made up of four components: TextField (a text input that activates a popover displaying a list of options, with filtering as merchants type), Popover (an overlay containing a list of options), Listbox (a list of options to filter and select or deselect), and Listbox.Option (individual options to select or deselect).
Combobox best practices
Combobox should be clearly labeled so merchants know what options are available. It should not be used within a popover. It should indicate a loading state while option data is being populated. Items should be ordered intentionally to make it easy for merchants to find a specific value.
Combobox sorting behavior
Item order should be intentional. Options can be sorted alphabetically or displayed based on how frequently merchants select them. If multiple options can be selected, selected items should be moved to the top of the list by default, though this behavior can be overridden.
Combobox filtering behavior
By default, menu items are filtered based on whether they match the value of the textfield. Filters are not case-sensitive by default. Custom filtering logic can be applied if the default behavior does not suit the use case.
Combobox accessibility based on ARIA 1.2 pattern
The Combobox component is based on the ARIA 1.2 combobox pattern and is a combination of a single-line TextField and a Popover, typically used with a Listbox component. The popover displays below the text field or other control by default, and the position can be changed with the preferredPosition prop.
Combobox accessibility consideration for assistive technologies
Combobox features can be challenging for merchants with visual, motor, and cognitive disabilities. Merchants should always be able to search, enter data, or perform other activities without relying on the combobox. Use combobox as progressive enhancement, not as a required interaction.
Combobox keyboard navigation
The combobox's text input can be given keyboard focus with the Tab key or Shift+Tab when tabbing backwards.
Combobox use cases and variants
Combobox has multiple variants: default single selection, single selection with manual entry, multi-select, multi-select with manual entry, and multi-select with vertical content display. It can also indicate loading states.
Combobox related components
For an input field without suggested options, use the TextField component. For a list of selectable options not linked to an input field, use the Listbox component.
Combobox component definition
Combobox is an accessible autocomplete input that enables merchants to filter a list of options and select one or more values.
Drop zone best practices for error handling
Drop zones should inform merchants when files cannot be uploaded. When possible, use validation errors on drag to detect and explain file size limits or file types accepted. Use the banner component with critical status to communicate errors that happen on the server. Provide feedback once files have been dropped and uploading begins.
Server-side upload error messages for drop zone
Server-side upload errors give feedback after file submission. Upload error messages should be displayed as a banner with critical status, show the name of the files that were not uploaded successfully, and describe why the files could not be uploaded and what merchants should change to upload successfully. Example format: 'The following images couldn't be uploaded: * "keep-it-real.png" is too large. Try a file size less than 20MB. * "realer-than-real.zip" is not supported. File type must be .gif, .jpg, .png or .svg. * "so-so-real.png" was interrupted due to weak network connection, [retry upload](#)'.
Drop zone file upload properties
The FileUpload subcomponent of drop zone has two properties. actionTitle (string, default 'Add file'): string that appears in file upload. actionHint (string, default 'or drop files to upload'): string that appears in file upload.
Drop zone accessibility keyboard support
The drop zone component builds on the native HTML input type upload element and includes a visual button as well as a drag-and-drop area that can receive keyboard focus. To upload a file with the keyboard, merchants can interact with the drag-and-drop region. To give the input keyboard focus, use the tab key or shift + tab when tabbing backwards. To activate the input, use the enter/return or space keys.
Drop zone variants by size
Drop zone has three size variants: default (for standard cases), medium-sized (for cases with limited space, recommended to nest in a larger drop zone with no outline), and small-sized (for tight space constraints such as variant thumbnails on the Product details page, recommended to nest in a larger drop zone with no outline).
Drop zone variants by content
Drop zone supports variants for different use cases: default drag-and-drop, with a label for better accessibility, image file upload, single file upload only, drop on page anywhere, accepts only specific file types, nested drop zones, and custom file upload text where child contents determine height.
Drop zone component purpose
The drop zone component lets users upload files by dragging and dropping the files into an area on a page, or activating a button.
Drop zone validation
The drop zone component validates file type by default. File types to accept can be defined by editing the accept property. The component also accepts custom validations using the customValidator property. When validation fails, the component sets itself to error mode.
Client-side validation error messages for drop zone
Client-side validation errors give instant feedback. Validation error messages should be explicit to help merchants understand why their file cannot be uploaded and what they should change to successfully upload. Messages should be in sentence case with only the first word capitalized. Messages should be concise using simple, clear language readable at a glance. Examples: 'File size must be less than 20MB' and 'File type must be .gif, .jpg, .png or .svg'.
Drop zone best practices for convenience
Drop zones should allow files to be dropped anywhere on the page by enabling dropOnPage. Provide a file upload button to allow merchants to select files for upload in a traditional way using the DropZone.FileUpload subcomponent.
Form implicitSubmit prop behavior
By default, the implicitSubmit prop is set to true. This allows merchants to submit the form with the enter/return key when focus is in any text field inside the form. If this behavior doesn't fit the form, set the prop to false.
Form component purpose
The form component is a wrapper component that handles the submission of forms.
Form component best practices
The form component should be used to wrap around all form input elements and emulate the native HTML form element behavior with a custom onSubmit callback.
Form component accessibility - HTML structure
The form component wraps content in an HTML <form> element. This helps to support assistive technologies that use different interaction and browse modes.
Form keyboard support
The form component supports keyboard submission via the enter/return key when focus is in any text field, providing a shortcut for keyboard users.
Form layout component relationship
To arrange fields within a form using standard spacing, use the form layout component.
Selection and input component category
Selection and input is a category of components for choosing or entering information using elements like checkboxes, text fields, and more.
Select component purpose and use cases
Select lets merchants choose one option from an options menu. The select component should be used for selecting between 4 or more pre-defined options. Consider select when you have 4 or more options, to avoid cluttering the interface.
Select default option best practice
A select component should have a default option selected whenever possible. Use 'Select' as a placeholder option only if there's no logical default option.
Select label content guidelines
Select labels should give a short description of 1–3 words of the requested input. They should be written in sentence case with the first word capitalized and the rest lowercase. Labels should avoid punctuation and articles ('the', 'an', 'a'). They must be independent sentences to support internationalization and should not act as the first part of a sentence finished by the component's options. Labels should be descriptive, not instructional. If the selection needs more explanation, use help text below the field.
Select options content guidelines
Select options should start with 'Select' as a placeholder if there isn't a default option. Options should be listed alphabetically or in another logical order so merchants can easily find the option they need. Options should be written in sentence case with the first word capitalized and the rest lowercase, and should avoid using commas or semicolons at the end of each option. Options should be clearly labelled based on what the option will do.
Select component variants
Select has the following variants: Default (presents a classic dropdown menu or equivalent picker as determined by merchants' browsers), With inline label (use only for cases where the select must fit on a single line, such as in a toolbar), Disabled (use for selections that aren't currently available, and the surrounding interface should make it clear why the select box is disabled and how to activate it), With prefix (renders any React element to the left of individual select options, does not show in the dropdown), With validation error (use to let merchants know if there's a problem with their selection), and With separate validation error (use to let merchants know when their select input is invalid in the context of a group of form inputs that the select depends on).
When to use choice list instead of select
To let merchants select one option from a list with less than 4 options, use the choice list component instead of select.