When to use option list and popover instead of select
To create a select where merchants can make multiple selections, or to allow advanced formatting of option text, use an option list inside a popover instead of the select component.
Shopify Polaris · all subjects
components
322 notes in this subject, read out of this brain and free to use. This is page 5 of 6.
Select validation error guidance
For selects, a selection is typically invalid only when using a placeholder option ('Select') and no other selection has been made.
Autocomplete off support by browser
Browser support for autocomplete='off' is partial across major browsers. Chrome intentionally ignores 'off' value when the user uses the browser's autofill functionality (see bug https://bugs.chromium.org/p/chromium/issues/detail?id=468153). Safari ignores 'off' value for username, email, and password fields. Firefox ignores 'off' value for login forms (see bug https://bugzilla.mozilla.org/show_bug.cgi?id=956906). Edge intentionally ignores 'off' value when the user uses the browser's autofill functionality.
Text field component description
A text field is an input field that merchants can type into. It has a range of options and supports several text formats including numbers.
Text field web component name and URL
The web component name is s-text-field. The documentation URL is https://shopify.dev/docs/api/app-home/polaris-web-components/forms/textfield.
Text field best practice: labeling
Text fields should be clearly labeled so it's obvious to merchants what they should enter into the field. Fields that request non-required input should be labeled as 'Optional'.
Text field best practice: validation timing
Validate input as soon as merchants have finished interacting with a field, but not before. If a field already has an error, validate and remove errors as merchants type so they can immediately see when an error has been fixed.
Text field best practice: minimal information
Only ask for information that's really needed.
Autocomplete attribute recommendation
Always add an autocomplete attribute and value to inputs if the type is: color, date, datetime-local, email, month, number, password, range, search, tel, text, time, url, or week. Autofill is an important feature for users. Google has found that users complete forms up to 30% faster when using autofill. Review WHATWG section 4.10.18.7 Autofill for all input types and their corresponding autocomplete attribute values.
Turning off browser autocomplete in Chrome
To turn off browser autocomplete (previously submitted values) in Chrome when you don't have a name attribute and the field is not a typical autofill input (address, email, etc), use autocomplete=off.
inputMode property for virtual keyboards
The inputMode property should be set to select the appropriate virtual keyboard for the type of data expected to be entered by the user.
Text field accessibility: disabled and readOnly props
Use the disabled prop to add the HTML disabled attribute to the text field. Use the readOnly prop to add the HTML readonly attribute to the text field.
Text field accessibility: type prop
If you use the type prop, then some assistive technologies adapt the software keyboard to the current task. This helps merchants with mobility, vision, and cognitive issues to enter information more easily.
Text field accessibility: id prop
Use the id prop to provide a unique id attribute value for the text field. If you don't provide an id, then the component generates one automatically. All text fields need to have unique id values.
Text field accessibility: label prop required
The label prop is required to convey the purpose of the text field to all merchants.
Text field accessibility: hidden label
If there are separate visual cues that convey the purpose of the text field to sighted merchants, then the label can be visually hidden with the labelHidden prop.
Text field accessibility: helpText and error aria-describedby
When you provide help text via the helpText prop or an inline error message via the error prop, the help or error content is conveyed to screen reader users with the aria-describedby attribute. This attribute causes the content to be read along with the label, either immediately or after a short delay.
Text field accessibility: placeholder guidance
Use the placeholder prop to provide additional instructions. However, don't rely on placeholders alone since the content isn't always conveyed to all merchants. Don't use the placeholder to provide information that's required to use the text field.
Text field accessibility: keyboard tab support
Merchants who rely on the keyboard expect to move focus to each text field using the Tab key (or Shift + Tab when tabbing backwards).
Text field accessibility: number type arrow keys
If the type is set to number, then merchants can use the up and down arrow keys to adjust the value typed into the field when hovering over or focusing the field to make the arrows appear.
Text field accessibility: disabled prevents keyboard focus
Using the disabled prop will prevent the text field from receiving keyboard focus or inputs.
Text field accessibility: readOnly allows focus
The readOnly prop allows focus on the text field but prevents input or editing.
Text field accessibility: inputMode prop for mobile
The inputMode prop can be used to bring up a relevant keyboard for merchants on mobile; it's passed down to the input as an inputmode attribute (https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode).
Text field accessibility: autoFocus prop default and guidance
Although you can use the autoFocus prop to automatically move focus to the text field, it's generally best to avoid focusing on fields automatically. The autoFocus prop is set to false by default and should only be used in cases where it won't force focus to skip other controls or content of equal or greater importance.
Utilities component category purpose
Utilities are core tools for managing the structure of the admin and global settings.
Image and video tile components: Small, Medium, Large, ExtraLarge
The Small, Medium, Large, and ExtraLarge components create section tiles for images, videos, and directives in documentation layouts. By default they apply no styles, but support additional styles through the variant prop.
Variant options for image/video tile components
The Small, Medium, Large, and ExtraLarge components support the following variant prop values: directive, do, dont, caution, and tip.
LayoutSection full width layout example
Example usage of LayoutSection with full width layout: ```mdx <LayoutSection> <Text></Text> <Small variant="do"></Small> <Small variant="dont"></Small> </LayoutSection> ```
Tile component variants example
Example showing variant prop usage for tile components: ```mdx <Small variant="directive">...</Small> <Small variant="do">...</Small> <Small variant="dont">...</Small> <Small variant="caution">...</Small> <Small variant="tip">...</Small> ```
Text component for documentation
The Text component creates a new tile for text content within documentation layouts on polaris.shopify.com.
LayoutSection component for documentation
The LayoutSection component creates a new content section in polaris.shopify.com documentation. It can contain other components like Text and image/video tiles.
Steps to contribute to Figma UI Kit
To contribute to the Figma UI Kit: (1) Submit an issue in the Shopify/polaris GitHub repo or assign yourself to an existing issue, ensuring you assign yourself to the issue, add the 'Figma UI Kit' label, use a descriptive title, and describe the change in the issue. (2) Create a branch in the Polaris Components Figma library with a descriptive name using the GitHub issue number (for example, '[4963] Navigation design changes'). (3) Make the necessary changes in the new branch. (4) Document all changes in the 'Release Notes' page within the UI kit. (5) Add a design reviewer from the Polaris team to review the changes on your branch, or share the link in the #polaris Slack channel if unsure who to add. (6) Once reviewed and approved, the Polaris designer will merge your changes into the main branch and publish the updates.
Figma branch naming convention
Figma UI Kit branches should use a descriptive name that ideally includes the GitHub issue number to make it easy to track. An example format is '[4963] Navigation design changes'.
Figma UI Kit contribution eligibility
Any designer that works at Shopify can contribute to the Figma UI Kit.
Figma UI Kit should only contain Polaris React components
Components, features, or patterns should not be added to the Figma UI Kit if they are not part of Polaris React. The goal is to keep Figma in sync with the code base. Only contributing changes to the Figma UI Kit when there is a counterpart in Polaris React prevents confusion and keeps tooling in sync across resources.
Component naming consistency
Be strategic and consistent when naming components. It makes it easier to create and build products and features for Shopify when people can switch between implementations and see the same names represented throughout. For example, use the same name across Rails, React, and Figma. It's okay if each implementation has its own spelling convention: 'Account connection' in documentation and Figma layer names, but 'ui_account_connection' in Rails and 'AccountConnection' in React.
Good component name qualities
A good component name can: increase adoption of a component; clarify where a component fits into the system; and help establish a mental model for people using the components.
Component naming conventions in documentation and code
Component names in documentation should describe the functionality they represent, avoid jargon so different disciplines understand its function, and be written in singular format. In documentation, write out the name without punctuation using sentence case (first word capitalized, rest lowercase). Examples: 'Type scale', 'Empty state'. In code, use the same name as documentation but alter the spelling convention to suit the implementation: 'TypeScale', 'EmptyState'.
Subcomponent naming conventions
For subcomponents in documentation, write out the name with a space between words using sentence case. Example: 'Layout section'. In code, use a period in place of the space. Example: 'Layout.Section'.
American spelling in component names
Use American spelling for all components. Correct: 'Layout.Center', 'Palette.Color'. Incorrect: 'Layout.Centre', 'Palette.Colour'. Exception: the Labelled component uses British spelling, following the 'aria-labelledby' attribute as per the ARIA specification.
Icon naming conventions
Icons should be named consistently so they are easy to find and implement across Shopify. Overall, icon names should: represent the intended function of the icon and avoid jargon so different disciplines understand its function.
Product area icon naming
Product area icons should only be used to symbolize their specific product area or function. Correct names: Home, Orders, Products. Incorrect: House, Invoice, Price tag.
Functional icon naming
Functional icons not tied to product areas should represent a clear action. Correct: 'Add image'. Incorrect: 'Image'.
Multi-function icon naming
Icons with more than one function should be named to represent their purpose and describe how they look. Correct: 'Circle alert', 'Camera', 'Clock'. Incorrect: 'Alert', 'Photography', 'Time'.
Consistency and predictability in Pro design language
Objects with similar appearance share a common behavior. Elements that are visually similar behave consistently throughout the interface. Consistency in behavior reduces confusion and cognitive load for merchants. By using consistent signifiers throughout the user experience, merchants can effectively apply the concepts they learn as they navigate the admin, enabling a smoother learning curve.
Polaris definition and purpose
Polaris is the design system for the Shopify admin.
Development resources location
The Shopify/polaris GitHub repo is an open-source monorepo containing NPM packages, VS Code extensions, and documentation. It is the primary source for development resources including React components, design tokens, and the VS Code extension.
Component lifecycle stages in Polaris
Polaris components move through a series of stages: Alpha, Beta, Stable, Legacy, and Deprecated. Each stage has specific requirements that must be met before a component can progress to the next stage.
Deprecated stage definition and expectations
Deprecated is the final stage where a component will be removed and should be avoided.
Alpha stage definition and expectations
Alpha is the initial stage where a component is a work in progress and ready for exploratory usage with breaking changes expected. During alpha, the purpose of the component and the problem it solves are being critically evaluated. Components could be changed completely or removed from the system without warning if the purpose is unclear. Usage is being evaluated and may not progress to beta.
Alpha requirements
Alpha components must: have a clear purpose and rationale for belonging in Polaris; use Polaris tokens with no hard-coded static values; be designed with responsiveness in mind and adapt across breakpoints; meet known accessibility requirements including contrast, interactive states, and touch target size; have in-progress documentation that includes the list of props with examples; include documentation examples in Storybook; have 100% test coverage.
Beta stage definition and expectations
Beta is the stage after alpha where there is a clear understanding of the problem and confidence in the solution. The focus is testing in enough environments to ensure the component is bug-free. Beta components are ready for wider adoption and encouraged for most cases. Breaking changes are possible in minor version updates. Work is being done to move to Stable, and manual and automated migration guidance is being developed.
Beta requirements
Beta components must: be used multiple times in production in Shopify admin; meet all accessibility requirements for the use cases; have usage guidelines and documentation covering common use cases; be reviewed and tested in production by designers and developers; have Figma components available in the Polaris Components file.
Stable stage definition and expectations
Stable is the stage where a component is bug-free and works in most, if not all, environments. Stable components are ready for full adoption with long-term support expected. The API is stable with no breaking changes until the next major release if necessary.
Stable requirements
Stable components must: have a stable API with no breaking changes until the next major release; have usability testing and feedback gathered on UX and DX; have documentation for component props, variants, accessibility guidelines, and usage; have manual and automated migration documentation.
Legacy stage definition and expectations
Legacy is the stage for components that are stable and have been supported in at least one past major release, but there are plans to replace their functionality with a new component or combination of components. Usage of legacy components is not discouraged, with the caveat that it will be deprecated and replaced in the next major release.
Legacy requirements
Legacy components must: have documentation for the legacy component that includes alternative components; have an announced deprecation date that is at least one month away from the release date of the package that deprecated the component; have documented manual and automated migration paths that have been available for at least one month.
Deprecation requirements
Deprecated components must: have documentation for the deprecation that includes alternative components; include deprecation warnings when used; have an announced removal date that is at least one month away from the release date of the package that removes the component; have documented manual and automated migration paths that have been available for at least one month.
Providing feedback on components at any lifecycle stage
Users can create an issue on GitHub to provide feedback, ask questions, or make suggestions about components during any stage of their lifecycle.
Modeled text inputs definition
Modeled text inputs are fields that require a specific format to be valid. They are often used for tags, dates, and some tracking numbers. Modeled text is highly structured, so providing examples is useful.