Listbox best practice - loading state indication
Listboxes should indicate a loading state to the merchant while option data is being populated.
Shopify Polaris · all subjects
components
322 notes in this subject, read out of this brain and free to use. This is page 3 of 6.
Listbox content guideline - option descriptions
Each item in a Listbox should be clear and descriptive. For example, use 'Traffic referrer source' rather than 'Source'.
Listbox accessibility - ARIA pattern
The Listbox component is based on the ARIA 1.2 Listbox pattern as defined at https://www.w3.org/TR/wai-aria-practices-1.2/#Listbox.
ResourceItem name prop must be unique
Each resource item should have a unique name prop for accessibility purposes.
ResourceItem must be wrapped in ResourceList
The resource item component must be wrapped in the resource list component.
ResourceItem accessibility label should be unique and convey purpose
For each ResourceItem, the accessibilityLabel prop should be used to give the link a unique aria-label value. The aria-label value should convey the link's purpose, using the name value. This helps merchants using screen readers or text to speech tools easily distinguish each link from the others.
ResourceItem keyboard activation and focus
ResourceItem links can be activated with the enter/return key by default. Custom controls added to resource items must be usable with the keyboard, receive keyboard focus in a logical order, and display a visible focus indicator.
ResourceItem accessibility for custom content
When adding custom content to resource items, ensure that all text is available to all users and that all custom controls have a unique accessible name to help users understand what will happen when the control is activated.
ResourceItem must be tailored to specific context type
Resource items should be tailored to the specific type of context being displayed, such as products or orders.
ResourceItem should perform an action when clicked
Resource items should perform an action when clicked. The action should navigate to the resource's details page or provide more detail about the item.
ResourceItem can provide shortcut actions
Resource items can optionally provide shortcut actions for quick access to frequent actions from the resource's details page.
ResourceItem media element options
The media element in a resource item can hold an avatar, thumbnail, or other small-format graphic.
ResourceItem content should avoid colons
Resource items should avoid using colons in their content.
ResourceItem shortcut actions don't need full verb + noun formula
Shortcut actions in resource items don't need to follow the full verb + noun formula required for regular buttons.
ResourceItem should present findable information
Resource items should present the information that merchants need to find the items that they're looking for.
ResourceItem should support merchant tasks
Resource items should support merchant tasks for the particular type of resource being displayed.
Tab labels must be clearly differentiated
Tab labels should be clearly labeled to help differentiate the different sections beneath them.
Tab labels should be short and scannable
Tab labels should have short and scannable labels, generally kept to single word.
Tab labels relate to invisible noun pattern
Tab labels should relate to the section of Shopify they're on. Imagine the page section title is an invisible noun after the tab. For example, the tabs for the orders section are: All, Open, Unfulfilled, Unpaid. The tabs for the gift cards section are: All, New, Partially used, Used, Disabled. The tabs for the customers section are: All, New, Returning, Abandoned checkouts, Email subscribers.
Fitted tabs use case
Fitted tabs should be used when tabs contain a few (2 or 3) items within a narrow column.
Tabs component purpose
Tabs are used to alternate among related views within the same context.
Default tabs use case
Default tabs should be used for most cases, especially when the number of tabs may be more than three.
Tabs inside card use case
Tabs can be used to display tabs inside of a Card component.
Tabs with actions use case
Tabs can be used when actions need to be performed on a tab.
Tabs with badge content use case
Tabs can be used with badge content to inform a piece of information about the tabs.
Tabs should represent same kind of content
Tabs should represent the same kind of content, such as a list-view with different filters applied. Don't use tabs to group content that is dissimilar.
Only one tab active at a time
Tabs should only be active one at a time.
Tabs should not force merchant context switching
Tabs should not force merchants to jump back and forth to do a single task. Merchants should be able to complete their work and find what they need under each tab.
Tabs are not for primary navigation
Tabs should not be used for primary navigation.
Link keyboard support
Links use browser defaults for keyboard interaction. Give links keyboard focus with the tab key (or shift + tab when tabbing backwards). Activate links with the enter or return key.
Link accessibilityLabel prop adds aria-label
The accessibilityLabel prop adds an aria-label attribute to the link, which can be accessed by assistive technologies like screen readers. This label text typically replaces the visible text on the link for merchants who use assistive technology.
Link consistency guidelines for accessibility labels
To provide consistency and clarity, use the same text for links that navigate to the same content and use different text for links that navigate to different content.
Link component purpose and placement
Links take users to another place and usually appear within or directly following a sentence. They are used primarily for navigation.
Buttons versus links distinction
Links are used primarily for navigation and usually appear within or directly following a sentence. Buttons are used primarily for actions, such as 'Add', 'Close', 'Cancel', or 'Save'. Plain buttons, which look similar to links, are used for less important or less commonly used actions, such as 'view shipping settings'. Using these components intentionally and consistently results in a more inclusive experience for assistive technology users, a more cohesive visual experience for sighted users, and products that are easier to maintain at scale.
External links open in new tab only when necessary
Default links should be used whenever possible to avoid disorienting merchants and causing accessibility problems by opening a new tab. External links should be used only when merchants are performing a task or workflow, like creating a product, or navigating to a page outside of the Shopify admin.
Avoid external icon with link text
Avoid using the external icon beside link text, as it can add unnecessary visual load inside a sentence or when accompanied by other content. Instead, add clarity to external links through clear link text and predictable placement of the link in a merchant's workflow. External icons should not be used to indicate a new tab or window is being opened, but may be used sparingly in features where symbols help merchants scan and pick from a list of several kinds of navigation options.
UnstyledLink component for custom styles
If the existing link styles don't meet the needs of a project, use the UnstyledLink component to create a custom link style.
Link url prop provides href and accessibility
Use the url prop to give the link component a valid href value. This allows the element to be identified as a link to assistive technologies and gives it default keyboard support.
Link underline for shape and interactivity indication
The Link component is underlined to give interactive elements a shape. This allows links to not rely on color as the only way users can tell if an element is interactive.
Link underline removal guidelines
Remove the link underline when the link is repeated in a list or navigation. Use underlines for links when used in inline content. Do not remove underlines when the user cannot determine the element's interactivity.
Links should navigate, not submit data
Merchants generally expect links to navigate, and not to submit data or take action. If a component that doesn't have a URL associated with it is needed, use the button component instead.
Link text must clearly describe purpose
Give links text that clearly describes their purpose.
Web component specification for Link
The Link component has a web component implementation named s-link available at https://shopify.dev/docs/api/app-home/polaris-web-components/actions/link.
Link component variants available
Link component has the following example variants: default links for text links inside a paragraph or standalone text that open in the same browser tab; monochrome for text links that are the same color as surrounding text; monochrome in a banner when used within a Banner component; and external link for text links that should open in a new browser tab.
Autocomplete best practices
The autocomplete component should: be clearly labeled so it is obvious to the merchant what type of options will be available; limit the number of options displayed at once; not be used within a popover; and indicate a loading state to the merchant while option data is being populated.
Autocomplete component purpose and use
The autocomplete component is an input field that provides selectable suggestions as a merchant types into it. It allows merchants to quickly search through and select from large collections of options. It is a convenience wrapper around the Combobox and Listbox components with minor UI differences.
Autocomplete component examples available
The autocomplete component has the following example variants: Default, With multiple tags, With multiple sections, With loading, With lazy loading, With empty state, With action, With wrapping action, and With destructive action.
Autocomplete content guidelines
The input field for autocomplete should follow the content guidelines for text fields.
Autocomplete related components
For an input field without suggested options, use the text field component. For a list of selectable options not linked to an input field, use the option list component. For a text field that triggers a popover, use the combo box component.
Autocomplete ARIA pattern compliance
The autocomplete component is based on the ARIA 1.2 combobox pattern and the ARIA 1.2 Listbox pattern from the W3C specifications.
Autocomplete list position default
The autocomplete list displays below the text field or other control by default so it is easy for merchants to discover and use. The position can be changed with the preferredPosition prop.
Autocomplete accessibility guidance
Autocomplete features can be challenging for merchants with visual, motor, and cognitive disabilities. Even when built using best practices, these features can be difficult to use with some assistive technologies. Merchants should always be able to search, enter data, or perform other activities without relying on the autocomplete.
Autocomplete should be progressive enhancement not requirement
Use autocomplete as progressive enhancement to make the interface easier to use for most merchants. Do not require that merchants make a selection from the autocomplete to complete a task.
Autocomplete keyboard support
Give the autocomplete text input keyboard focus with the Tab key (or Shift+Tab when tabbing backwards). Access the list of options with the up and down arrow keys. Select an option that has focus with the Enter/Return key.
Popover ariaHaspopup role guidance
Web browsers assign a default value of 'menu' to the `aria-haspopup` role. You can use the prop `ariaHaspopup` to specify a value. Screen readers may fail to send focus to the Popover content when they expect the content to be adjacent to the element with `aria-haspopup` in the DOM tree. In this scenario, it is recommended not to provide the `ariaHaspopup` prop.
Popover trigger button best practice
Popovers should be triggered by a clearly labeled button. A default or tertiary button should be used as the activator.
Popover keyboard support - focus on open
When a popover opens, focus moves to the first focusable element or to the popover container.
Popover keyboard support - focus management in popover
Once focus is in the popover, merchants can access controls in the popover using the tab key (and shift+tab backwards) and standard keystrokes for interacting.
Popover keyboard support - dismiss
Merchants can dismiss the popover by tabbing out of it, pressing the esc key, or clicking outside of it.
Popover action clarity content guideline
If a popover contains actions, they should be clear and predictable. Merchants should be able to anticipate what will happen when they click on an action item. Never deceive merchants by mislabeling an action. For example, use 'Create order' or 'Buy shipping label' rather than 'New order' or 'Buy'.