Form layout supports horizontal groups of fields
Form layout also supports horizontal groups of fields in addition to the default vertical stacking.
Shopify Polaris · all subjects
components
322 notes in this subject, read out of this brain and free to use. This is page 2 of 6.
Field label example: Email address
A well-formed field label is 'Email address' (do). Poor examples include 'What is your email address?' and 'My email address is:' (do not).
Field group arranges multiple fields in a row
Field groups are used to arrange multiple fields in a row. They work best for familiar layouts such as a row of city, state, and zip code fields. Field groups will wrap automatically on smaller screens.
Condensed field group for short inputs
For very short inputs, condensed field groups can be used to reduce the width of the inputs in order to fit more fields in the row.
Form layout default behavior stacks fields vertically
By default, Form layout stacks fields vertically, which makes them easier to scan and complete.
Form layout component purpose
The Form layout component manages the layout of all forms and fields within them. It is used for laying out new forms and managing the layout of all forms.
Form best practice: logical and predictable order
Forms should follow a logical, predictable order. For example, always ask for first name first, and last name second on forms.
Form best practice: only ask for required information
Forms should be considerate of merchants' time and privacy by only asking for information that is required.
Form layout pitfall: avoid unrelated fields side by side
When using field groups to arrange multiple fields in a row, caution should be used when arranging unrelated fields next to each other as this makes fields easier to miss.
Help text should be succinct and easy to read
Help text provides extra guidance to people filling out a form field. This text is easy for people to ignore, so merchants should not need to depend on it to fill out a form. Help text should be succinct and easy to read.
Form best practice: group related tasks under section titles
Forms should group related tasks under section titles to provide more context and make the interface easier to scan.
Field label example: Phone number
A well-formed field label is 'Phone number' (do). Poor examples include 'My phone number is:' (do not).
Layout compositions built from primitives
Layout compositions are built with layout primitives and are used to create common layouts in the admin with sensible defaults.
Layout primitives support responsive props
Layout primitives allow you to specify values for different screen sizes. Each primitive component documents how responsive props apply to it.
Layout primitives naming conventions
Component naming conventions for layout primitives follow web standards for logical properties and values as documented by MDN.
Layout primitives list
The layout primitives in Polaris are: Bleed, Block stack, Box, Divider, Grid, Inline stack, and Inline grid.
Layout and structure component category overview
Layout and structure components help merchants understand and find information to complete their goals through arrangement of elements on a page. All layouts and spacing should be handled using layout primitives to keep components simple, flexible, and composable.
InlineStack CSS logical properties naming convention
InlineStack props are named following the convention of CSS logical properties, such as align="start" vs align="left" and blockAlign="end" vs verticalAlign="bottom". This follows CSS logical properties standards as documented at https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties.
InlineStack related component for large-scale page structure
To create the large-scale structure of pages, use the InlineGrid component instead of InlineStack.
InlineStack related component for vertical display
To display elements vertically, use the BlockStack component instead of InlineStack.
InlineStack align prop
The align prop controls the horizontal alignment of children.
InlineStack blockAlign prop
The blockAlign prop controls the vertical alignment of children.
InlineStack gap prop and responsive spacing
The gap prop controls the horizontal and vertical space between children. The gap prop supports responsive spacing with Breakpoints tokens.
InlineStack component purpose
InlineStack displays children horizontally in a row. It is based on CSS Flexbox.
InlineStack web component name
The web component name for InlineStack is s-stack, documented at https://shopify.dev/docs/api/app-home/polaris-web-components/structure/stack.
InlineStack direction prop and responsive spacing
The direction prop controls the horizontal direction of children. The direction prop supports responsive spacing with Breakpoints tokens.
InlineStack wrap prop behavior
The wrap prop controls the wrapping behavior of children. The default wrapping behavior can be overridden using the wrap prop.
Media card examples
Media card has the following example variants: Default (use to surface educational information about a feature or opportunity); With small visual (use when there are limited vertical space, or when the card should be less prominent); With secondary action (use when there are two distinct actions merchants can take on the information in the card); With no actions (use when media card does not require any actions); Video card (use to provide a consistent layout for contextual learning content and to wrap thumbnails of educational videos about Shopify features in context); Portrait video card (use when vertical screen space is not limited or when the video card is the page's primary content, such as in an empty state).
Media card body content guidelines
Body content should be actionable by starting sentences with imperative verbs when telling merchants what actions are available to them, especially something new, and not use permissive language like 'you can'. Body content should be structured for merchant success by always putting the most critical information first. Body content should be clear by using the verb 'need' to help merchants understand when they're required to do something, rather than 'must'.
Media card best practices
Media cards should: provide merchants with a clear call to action; always pair text with a visual component such as body text with an image or video; use media to enhance the written content where the written content should be able to stand alone without an explanation from the paired media; show targeted content toward specific audiences to maximize relevance; and be dismissable.
Media card purpose and use cases
Media cards provide a consistent layout to present visual information to merchants. Visual media is used to provide additional context to the written information it's paired with. Media cards are often used in a grid to present related content and provide a container for introductory or highlight information.
Media card content guidelines - don't use as advertisement
Media cards should not be used as advertisements for a feature. Instead they should educate the merchant about how to accomplish tasks related to the section they're in.
Media card accessibility requirements
Media cards should use actionable language to ensure that the purpose of the media card is clear to all merchants, including those with issues related to reading and language.
Media card title accessibility
The required title prop gives the media card a level 2 heading (<h2>). This helps with readability and provides structure to screen reader users. The title prop can also accept a ReactNode.
Media card button content guidelines
Buttons should be clear and predictable so merchants can anticipate what will happen when they click. Buttons should be action-led, always leading 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. Buttons should be scannable by avoiding unnecessary words and articles such as 'the', 'an', or 'a'.
Lists component purpose
Lists provide merchants with easy-to-use interfaces for selecting options, organizing information, and interacting with data.
Action list example variants available
Action list has documented examples for: in a popover, with icons or image, with an icon and a suffix, with sections, with destructive item, with help text, and with a prefix and a suffix.
Action list keyboard support: activation
Activate action list item buttons with the enter/return key or the space key.
Action list high contrast support
Each item is clearly discernible in high contrast mode. Each item that is focused and hovered is clearly discernible in high contrast mode.
Action list content: avoid articles and unnecessary words
Each item in an action list should be scannable by avoiding unnecessary words and articles such as the, an, or a. Write 'Add menu item' instead of 'Add a menu item'.
Action list keyboard support: tab navigation
Give the action list items keyboard focus with the tab key (or shift + tab when tabbing backwards).
Action list accessibility: structure
Items in an action list are organized as list items (<li>) in an unordered list (<ul>) and are conveyed as a group of related elements to assistive technology users. Each item is implemented as a button.
Action list best practice: secondary actions
Action lists should be used for secondary or less important information and actions since they're hidden until merchants expose them by opening a popover.
Action list content: strong verb requirement
Each item in an action list should always lead with a strong verb that encourages action. Use the {verb}+{noun} format to provide enough context unless the action is clear with a single verb. Examples of correct format: 'Rename', 'Edit HTML'. Examples to avoid: 'File name changes', 'HTML editing options'.
Action list content: clarity and predictability
Each item in an action list should be clear and predictable. Merchants should be able to anticipate what will happen when they click on an action item.
Action list keyboard support: arrow navigation
When action list items have a role of menuitem, navigate through the list with down arrow (up arrow to move backwards).
Action list best practice: related actions
Action lists should contain actions that are related to each other.
Action list component definition
Action lists render a list of actions or selectable options. This component is usually placed inside a popover container to create a dropdown menu or to let merchants select from a list of options.
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 best practice - limit options displayed
Listboxes should limit the number of options displayed at once.
Listbox best practice - clear labeling
Listboxes should be clearly labeled so it is noticeable to the merchant what type of options will be available.
Listbox composition - Section headers
Section headers are used at the beginning of a section in a Listbox when it is necessary to call out the content being displayed. In most cases, the surrounding context should be enough for the merchant to understand the information in the list.
Listbox composition - Dividers
Dividers are placed between items in a Listbox and are useful in complex lists when there is a lot of information for the merchant to parse.
Listbox component definition
A Listbox is a vertical list of interactive options, with room for icons, descriptions, and other elements. It allows merchants to select options from a displayed list.
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.
Listbox accessibility - interactive elements restriction
It is important to not present interactive elements inside of list box options as they can interfere with navigation for assistive technology users.
Listbox keyboard support - navigation
Merchants can access the list of options and navigate through them using the up and down arrow keys.
Listbox best practice - loading state indication
Listboxes should indicate a loading state to the merchant while option data is being populated.
Listbox composition - Options
Options are the individual interactive items inside the Listbox that merchants can select or deselect.
Listbox keyboard support - selection
Merchants can select an option that has focus by pressing the Enter or Return key.