Images and icons component category
Images and icons is a component category in Polaris that represents visual content, such as avatars and thumbnails for images or video.
Shopify Polaris · all subjects
components
322 notes in this subject, read out of this brain and free to use. This is page 1 of 6.
Components are reusable building blocks
Components are the reusable building blocks for creating Shopify admin experiences.
Accessibility labels for thumbnails on iOS
On iOS, set imageView.accessibilityLabel = "Photo of {product}" following the format, such as "Photo of black t-shirt with cartoon tiger".
Thumbnail purpose and usage
Thumbnails are used as a visual anchor and identifier for an object, along with text to provide context.
Alt text format for thumbnails on web
For thumbnails on web, use alt text in the format 'Photo of {product}', such as 'Photo of black t-shirt with cartoon tiger'. An empty alt="" attribute ignores the image in assistive technologies such as screen readers and may be used on decorative thumbnails.
Thumbnail web component reference
The Thumbnail component is available as a web component named s-thumbnail. Documentation is available at https://shopify.dev/docs/api/app-home/polaris-web-components/media/thumbnail.
Thumbnail sizes on mobile platforms
Thumbnails on Android and iOS come in 2 sizes: Default (40 × 40) as the default size; Large (72 × 72) when thumbnail is a major focal point, avoid in lists of like items.
Content description for thumbnails on Android
On Android, set android:contentDescription="Photo of {product}" following the format, such as "Photo of black t-shirt with cartoon tiger".
Thumbnail sizes on web
Thumbnails on web come in 4 sizes: Extra small (24 × 24 px) for tightly condensed layouts; Small (40 × 40 px) when the medium size is too large or thumbnail has less importance; Medium (60 × 60 px) as the default size; Large (80 × 80 px) when thumbnail is a major focal point, avoid in lists of like items.
Frame best practice components
When creating an application frame, use these components: Top Bar, Navigation, Contextual Save Bar, Toast, and Loading.
Frame is internal only
The Frame component is marked as internal only and is hidden from the main navigation documentation.
Frame component purpose and structure
The Frame component creates the structure of the Shopify admin. It is not visible in the user interface itself but wraps the main elements and houses the primary Navigation, Top Bar, Toast, and Contextual Save Bar components.
Loading component accessibility implementation
The loading component is implemented using the ARIA 1.1 progressbar pattern. It outputs an ARIA role="progressbar" and uses aria-valuemin, aria-value-max, and aria-valuenow to convey the loaded percentage to screen reader users.
Loading component must be wrapped in frame
The loading component must be wrapped in the frame component.
Loading component best practices
The loading component should: indicate that the page requested is loading; indicate that an upload has started and the action will soon complete; be used to give feedback for an entire page load or a page mutation like saving a product; be used alongside a component or page element that contains aria-busy to represent what is loading.
Loading component purpose
The loading component is used to indicate to merchants that a page is loading or an upload is processing.
Loading component related components
To indicate that an action has been received, use the Spinner component. To improve user experience and reduce the appearance of long loading times, use the Progress bar component. To better represent loading content, use Skeleton page along with Skeleton body text and Skeleton display text components.
Top bar search placeholder content
The placeholder content for the search field should always say 'Search' and never include an ellipsis.
Top bar user menu properties
The top bar user menu component has the following properties: actions ({items: IconableAction[]}[]) - an array of action objects that are rendered inside of a popover triggered by this menu; message (MessageProps) - accepts a message that facilitates direct, urgent communication with the merchant through the user menu; name (string) - a string detailing the merchant's full name to be displayed in the user menu; detail (string) - a string allowing further details on the merchant's name displayed in the user menu; initials (AvatarProps['initials']) - the merchant's initials, rendered in place of an avatar image when not provided; avatar (AvatarProps['source']) - an avatar image representing the merchant; open (boolean) - a boolean property indicating whether the user menu is currently open; onToggle() (function) - a callback function to handle opening and closing the user menu.
Top bar menu properties
The top bar menu component has the following properties: activatorContent (React.ReactNode) - accepts an activator component that renders inside of a button that opens the menu; actions (ActionListProps['sections']) - an array of action objects that are rendered inside of a popover triggered by this menu; message (MessageProps) - accepts a message that facilitates direct, urgent communication with the merchant through the menu; open (boolean) - a boolean property indicating whether the menu is currently open; onOpen() (function) - a callback function to handle opening the menu popover; onClose() (function) - a callback function to handle closing the menu popover.
Top bar should not provide global navigation
The top bar component should not provide global navigation for an application. Use the navigation component instead.
Top bar best practices
The top bar component should include search to help merchants find resources and navigate an application. It should include a user menu component to indicate the logged-in merchant and provide them with global actions. It should provide a color through the app provider component to style the background. The global menu text should contrast with the rest of the top bar and pass the minimum contrast ratio of the WCAG 2.0 guidelines. An SVG file should be used for the logo. A logo should pass the minimum contrast ratio of the WCAG 2.0 guidelines when compared to the top bar background color. The navigation toggle should be shown so it appears on small screens.
Top bar search field properties
The top bar search field component has the following properties: value (string) - initial value for the input; placeholder (string) - hint text to display; focused (boolean) - force the focus state on the input; active (boolean) - force a state where search is active but the text field component is not focused; onChange(value: string) (function) - callback when value is changed; onFocus() (function) - callback when input is focused; onBlur() (function) - callback when focus is removed.
Top bar must be passed to frame component
The top bar component must be passed to the frame component.
Top bar menu message properties
The top bar menu message component has the following properties: title (string) - a title for the message; description (string) - a description for the message; action ({onClick(): void; content: string}) - an action to render near the message; link ({to: string; content: string}) - a link to view the content of the message; badge ({content: string; status: BadgeProps['status']}) - a badge to render near the message.
Top bar internal-only component
The top bar is marked as internal-only, indicating it is designed for Shopify internal use.
Top bar purpose and placement
The top bar is a header component that appears at the top of the page and is used to brand and navigate major applications areas. It's always visible at the top of interfaces like Shopify or Shopify Plus. The top bar allows merchants to search, access menus, and navigate by clicking on the logo.
Top bar theme customization through app provider
Third-party apps that use the top bar can customize the color to match their brand using the app provider component. Providing just the background key for the top bar component theme will result in intelligent defaults being set for complementary colors with contrasting text. Third-party apps are required to use their own logo.
Navigation section action properties
Action properties are: icon (IconProps['source'], an icon to display as the content of the action), accessibilityLabel (string, visually hidden label for screen readers), onClick() (function, callback to handle clicking on the action), tooltip (TooltipProps, options for displaying a tooltip when you hover over the action button).
Navigation section properties
Navigation section properties are: items (Item[], a collection of navigation items to be rendered inside the section), icon (IconProps['source'], an icon to be displayed next to the section title), title (string, a title for the navigation section), fill (boolean, whether the section should take up all vertical space available), rollup (Rollup, an object determining the collapsing behavior of the section), action (Action, renders an icon-only action as a supplementary action next to the section title), separator (boolean, whether the section should have a visual separator).
Navigation section rollup properties
Rollup properties are: after (number, a number of items after which the navigation section should be collapsed), view (string, content for the section view action), hide (string, content for the section hide action), activePath (string, the current URL of your application).
Navigation best practices
The navigation component should contain primary navigation items that perform an action when clicked. Only use secondary actions for supplementary actions to primary actions. Group navigation items into sections based on related categories. Use a section title to clarify the category of a section. Use major icons for item actions and minor icons for secondary actions. Use the provided navigation section component to group navigation items. Do not add additional components like badges in navigation items.
Navigation component requires frame component
The navigation component must be passed to the frame component. The mobile version of the navigation component appears in the top bar component.
SubNavigationItem properties
SubNavigationItem properties are: url (string, a location for the item to navigate to when clicked), matches (boolean, whether the item should respond to a closely matching location property), exactMatch (boolean, whether the item should respond to an exactly matching location property), matchPaths (string[], additional paths for the item to respond to), excludePaths (string[], paths the item should not respond to), external (boolean, whether this is an external link; if true, an external link icon will be shown), label (string, content to display as link text), disabled (boolean, whether the item is disabled), new (boolean, add an indicator dot to the parent and badge to the item, overwritten by the badge prop), onClick() (function, callback to handle clicking).
Navigation item properties
Navigation item properties are: url (string, a location for the item to navigate to when clicked), matches (boolean, whether the item should respond to a closely matching location property), exactMatch (boolean, whether the item should respond to an exactly matching location property), matchPaths (string[], additional paths for the item to respond to), excludePaths (string[], paths the item should not respond to), icon (IconProps['source'], an icon to display next to the navigation—prefer minor icons; if a major icon is used, set shouldResizeIcon to true), badge (string|null, content to display in a badge next to the item), label (string, content to display as link text), disabled (boolean, whether the item is disabled), new (boolean, add an indicator dot to the parent and badge to the item, overwritten by the badge prop), accessibilityLabel (string, visually hidden label for screen readers), selected (boolean, whether the item is currently selected), shouldResizeIcon (boolean, allow major icons to be displayed at the same size as minor icons), subNavigationItems (SubNavigationItem[], nested secondary navigation items), secondaryAction (SecondaryAction, renders an icon-only action as a supplementary action), secondaryActions (SecondaryAction[], renders one or two icon-only actions as supplementary actions), onClick() (function, callback to handle clicking), truncateText (boolean, allow text that exceeds width to be truncated with ellipsis), displayActionsOnHover (boolean, only display secondary actions when the navigation item is hovered on desktop).
Navigation content case rules
Primary and secondary navigation items should use sentence case. Section labels should use all caps. Labels should use as few words as possible to describe each item.
Navigation component purpose
The navigation component displays the primary navigation in the sidebar of the frame component of an application. Navigation includes a list of links that merchants use to move between sections of the application.
SecondaryAction properties
SecondaryAction properties are: url (string, a location for the item to navigate to when clicked), accessibilityLabel (string, visually hidden label for screen readers), icon (IconProps['source'], an icon to display next to the navigation—prefer minor icons; if a major icon is used, set shouldResizeIcon to true), onClick() (function, callback to handle clicking), tooltip (TooltipProps, options for displaying a tooltip when you hover over the action button).
BlockStack web component name and URL
The BlockStack web component is named s-stack and documented at https://shopify.dev/docs/api/app-home/polaris-web-components/structure/stack
BlockStack naming convention for props
BlockStack props follow CSS logical properties naming convention. Use align="start" instead of align="top", and inlineAlign="end" instead of verticalAlign="right".
BlockStack component purpose and usage
BlockStack is used to display children vertically and horizontally with full width by default. It is based on CSS Flexbox.
BlockStack gap prop
The gap prop controls the vertical space between children in a BlockStack.
BlockStack should not be used for page layout
BlockStack should not be used for large-scale page layout.
BlockStack should not be used for complex arrangements
BlockStack should not be used for complex or unique arrangements of components.
Divider web component documentation
The web component documentation for Divider is available at https://shopify.dev/docs/api/app-home/polaris-web-components/structure/divider
Divider border color customization
Divider border color can be adjusted using Color tokens.
Divider web component name
The web component for Divider is named 's-divider'.
Divider purpose and usage
The Divider component is used to separate or group content.
Divider keywords
Divider is associated with keywords: layout, divider, border.
Callout card actionable language accessibility
Use actionable language to ensure that the purpose of the callout card is clear to all merchants, including those with issues related to reading and language.
Callout card purpose and use cases
Callout cards are used to encourage merchants to take an action related to a new feature or opportunity. They are most commonly displayed in the sales channels section of Shopify.
Callout card title accessibility
The required title prop gives the callout card a level 2 heading (<h2>). This helps with readability and provides structure to screen reader users.
Callout card illustration accessibility
Illustrations included in callout cards are implemented as decorative images with empty alt attributes (alt="") so that they're skipped by screen readers.
Callout card body content clarity with 'need'
Use the verb 'need' to help merchants understand when they're required to do something. For example, write 'To buy a shipping label, you need to enter the total weight of your shipment, including packaging' instead of 'To buy a shipping label, you must enter the total weight of your shipment, including packaging'.
Callout card body content structure
Body content should always put the most critical information first and be structured for merchant success.
Callout card body content should be actionable
Body content should start sentences with imperative verbs when telling merchants what actions are available to them, especially something new. Do not use permissive language like 'you can'. For example, write 'Get performance data for all your sales channels' instead of 'Now you can get performance data for all your sales channels'.
Callout card best practices
Callout cards should: clearly articulate the benefit of the feature and what it does; provide merchants with a clear call to action; be targeted to merchants who will most benefit from the feature; be dismissable so merchants can get rid of cards about features they're not interested in; use an illustration that helps to communicate the subject or merchant benefit.
Form section title content guidelines
Form section titles should follow the content guidelines for headings and subheadings as documented in the actionable language section.
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.
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.