Caption component is deprecated
The Caption component is no longer supported. Developers should use the Text component instead.
Shopify Polaris · all subjects
deprecated-components
72 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
Caption to Text migration path
To migrate from Caption to Text component, use Text with variant='bodySm' and as='p'. For example, replace <Caption>Received April 21, 2017</Caption> with <Text variant='bodySm' as='p'>Received April 21, 2017</Text>.
Caption component use cases
Caption text size is smaller than the recommended size for general reading. On web, it should be used only in a graph or as a timestamp for a list item. On Android and iOS, it can also be used as help text or as other kinds of secondary text for list items.
DisplayText component is deprecated
The DisplayText component is no longer supported and should not be used. Developers should use the Text component instead.
DisplayText to Text component migration - extra large size
To migrate from DisplayText with size="extraLarge", use the Text component with variant="heading3xl" and as="p". Example: <Text variant="heading3xl" as="p">Sales this year</Text>
Fullscreen bar is deprecated
The Fullscreen bar component is no longer supported. Use the App Bridge Modal API in combination with the App Bridge Title Bar API instead.
Fullscreen bar purpose and behavior
The Fullscreen bar is a header component presented at the top of an app when in fullscreen mode to ensure uniform placement for a button to exit that mode. It can be customized by adding children.
Fullscreen bar best practices
The Fullscreen bar component should be presented when an app is in fullscreen mode as a means of exiting that mode, and should fire an action to exit fullscreen mode.
Deprecated components will be removed in future major versions
Deprecated components will be removed in future major versions of Polaris. These components should be avoided as they could be deprecated for various reasons outlined in the component lifecycles documentation. Deprecated components will show warnings in the component file and provide details for alternative usage.
Where to find information about component deprecation reasons
Information about the reasons for component deprecation can be found in the component lifecycles documentation under the requirements for deprecation section.
Legacy Filters badge naming when ambiguous
If a filter name is ambiguous on its own, add a descriptive word related to the status. For example, use 'High risk, Low risk' instead of just 'High, Low' so merchants understand the context.
Legacy Filters badge truncation when all selected
When all filter tags from a category are selected, truncate the tag display in the middle. For example, display 'Paid, par… unpaid' rather than 'All payment status filters selected, Paid, unpa…'.
Legacy Filters badge grouping rule
Group filter badges from the same category together. For example, display 'Unfulfilled, Fulfilled' together rather than separating them as 'Unfulfilled' and 'fulfilled'.
Legacy Filters component accessibility dependencies
The Legacy Filters component relies on the accessibility features of the following components: Text field, Button, Popover, Sheet, and Collapsible.
Legacy Filters component status
The Legacy Filters component is deprecated and no longer supported. The new Filters component can be used as a standalone component, but is used primarily within the IndexFilters for sorting and filtering IndexTables.
Legacy Filters component purpose
Legacy Filters is a composite component that filters the items of a list or table. Merchants use filters to view different subsets of items in a list or table, filter by typing into a text field, and filter by selecting filters or promoted filters.
Legacy Filters custom content accessibility requirement
Since custom HTML can be passed to the Legacy Filters component for additional actions, the filtering system must be accessible as a whole. All merchants must be able to identify and understand labels for all controls, be notified of state changes, and be able to complete all actions with the keyboard.
Legacy Filters best practices for promoted filters
The Legacy Filters component should include no more than 2 or 3 promoted filters to help reduce merchant effort by promoting the filtering categories that are most commonly used.
Legacy Filters best practices for responsive design
When designing the interface for each filter and determining the total number of filters to include in the Legacy Filters component, consider small screen sizes.
Legacy Filters best practices for children content
The Legacy Filters component should use children only for content that is related or relevant to filtering.
Legacy Filters text field label content guideline
The text field in the Legacy Filters component should be clearly labeled so it is obvious to merchants what they should enter into the field. The label should use action-oriented language like 'Filter orders' rather than generic instructions like 'Enter text here'.
Legacy Filters badge naming when purpose is clear
Use the name of the filter if the purpose of the name is clear on its own. For example, filter badges that read 'Fulfilled' or 'Unfulfilled' are intuitive without additional context. Do not add redundant category prefixes like 'Fulfillment: Fulfilled'.
Default tabs usage
Use the default tab variant for most cases, especially when the number of tabs may be more than three.
Legacy tabs component deprecated status
The Legacy tabs component is no longer supported. The new Tabs component can be used as a standalone component but is primarily used within IndexFilters for navigating and creating saved views of filtered IndexTables. Refer to component lifecycles documentation for more information.
Tabs best practice: no back and forth navigation
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.
PageActions secondary actions limit
Page actions should include a maximum of two secondary actions, but does not have to include any secondary actions.
PageActions component is deprecated
The Page actions component is no longer supported. Developers should use the App Bridge Save Bar API instead (https://shopify.dev/docs/api/app-bridge-library/apis/save-bar).
PageActions primary action placement
Page actions should include a single primary action on the right. It should be the same as the primary action that shows in the title bar at the top of the page.
PageActions typical use case
Page actions are used on resource pages (such as an individual order or product page) to let merchants take key actions at the bottom of the page. Usually, the primary action is Save and the secondary action is Delete.
Sheet keyboard support requirements
The sheet must implement keyboard support as follows: use the onClose prop so the sheet can be closed with the Esc key and button-based controls; use a button to open the sheet; when the sheet opens, focus must move to it so merchants using keyboard and screen readers can access it; focus must be kept in the sheet until it is dismissed; when the sheet closes, focus must move back to the button that launched it.
Sheet component status
The Sheet component is deprecated. It should not be used in new implementations.
Sheet purpose and behavior
A sheet is a large container that enters from the edge of the screen when triggered by the merchant. It provides merchants with actions and information contextual to the page without interrupting their flow like a modal would. Merchants may see content in the sheet and the main page at the same time, but should only be expected to interact with one or the other at any given time.
Sheet responsive behavior
At small screen sizes, the sheet component enters the page from the bottom of the screen. At larger screen sizes, the sheet component enters the page from the right side of the screen.
Sheet best practices
The sheet component should: include a heading that summarizes the actions and information in the sheet (for example, 'More filters'); be openable through clear actions like a link or button; be closeable through clear actions like Done, an X button, and the Esc key; include information and actions contextual to the current task; not block merchants from completing their task like a modal would; not open from within another sheet (only one sheet can be open at a time); preserve its state so settings and actions won't reset when closed.
Sheet backdrop behavior
The sheet uses a transparent backdrop. The backdrop is a full screen overlay which closes its parent component when pressed. This design choice allows merchants to see elements behind the sheet.
Sheet deprecation rationale
The sheet component is deprecated because it encourages designers to create a new layer on top of the page instead of improving the existing user interface. It also blocks other parts of the UI, forces users to switch context, and adds complexity to otherwise simple interactions.
Sheet alternatives
To offer an action before merchants can proceed to the next step in the flow, use the modal component. To present a small amount of content or a menu of actions in a non-blocking overlay, use the popover component.
Modal focus management for accessibility
After a modal is closed, focus should return to the button that launched it. Pass the button to the modal as an activator prop. To ensure that Toasts are read out by a screen reader when a Modal is open, apps should be wrapped in a Frame component.
Modal keyboard support
Modal keyboard support requirements: (1) When a modal opens, focus moves automatically to the modal container so it can be accessed by keyboard users. (2) While the modal is open, keyboard focus shouldn't leave the modal. (3) Merchants can dismiss the modal with the keyboard by activating the X button, the Cancel button if one is provided, or by pressing the Esc key. (4) After a modal is closed, focus returns to the button that launched it.
Modal component is deprecated
The Modal component is no longer supported. Use the App Bridge Modal API instead.
Modal best practices
Modals should: (1) Require that merchants take an action. (2) Close when merchants press the X button, the Cancel button, the Esc key, or when merchants click or tap the area outside the modal. (3) Not have more than two buttons (primary and secondary) at the bottom to prevent unclear action hierarchy and crowding on mobile screens. Since modals are for focused tasks, they should have focused actions. In some cases however, a tertiary action may be appropriate.
Modal title content guidelines
Modal titles should: (1) Use a clear {verb}+{noun} question or statement. (2) Follow the content guidelines for headings and subheadings. Good examples: 'Edit email address', 'Delete customer?', 'Discard unsaved changes?'. Avoid: 'Edit the email address for this order', 'Are you sure you want to delete customer?', 'Discard?'
Modal body content guidelines
Body content should be: (1) Actionable: start sentences with imperative verbs when telling a merchant what actions are available to them (especially something new). Don't use permissive language like 'you can'. Example: 'Notification emails will be sent to this address.' vs 'You can edit the email address where emails will be sent.' (2) Structured for merchant success: always put the most critical information first. (3) Clear: use the verb 'need' to help merchants understand when they're required to do something. Example: 'To buy a shipping label, you need to enter the total weight of your shipment, including packaging.' instead of 'you must'.
Modal action button content guidelines
Actions should be: (1) Clear and predictable: merchants should be able to anticipate what will happen when they click a button. Never deceive a merchant by mislabeling an action. Good examples: 'Create order', 'Buy shipping label'. Avoid: 'New order', 'Buy'. (2) Action-led: actions should always lead with a strong verb that encourages action. Use the {verb}+{noun} format on actions except in the case of common actions like Save, Close, Cancel, or OK. Good examples: 'Activate Apple Pay', 'View shipping settings'. Avoid: 'Try Apple Pay', 'View your settings'. (3) Scannable: avoid unnecessary words and articles such as the, an, or a. Good example: 'Add menu item'. Avoid: 'Add a menu item'.
Modal tertiary actions guidelines
Tertiary actions should: (1) Only be used when the action requires the context of the content in the modal. (2) Never be used to dismiss the modal. Use a plain button for a tertiary action if needed. Do not use a tertiary action for a destructive action.
Modal footer content guidelines
Footer content should be: (1) Actionable: start sentences with imperative verbs when telling a merchant what actions are available to them (especially something new). Don't use permissive language like 'you can'. Example: 'Notification emails will be sent to this address.' vs 'You can edit the email address where emails will be sent.' (2) Structured for merchant success: always put the most critical information first. (3) Clear: use the verb 'need' to help merchants understand when they're required to do something. Example: 'To buy a shipping label, you need to enter the total weight of your shipment, including packaging.' instead of 'you must'.
Modal ARIA role and labeling
Modals use ARIA role="dialog" to convey to screen reader users that they work like native dialog windows. If the title prop is set to give the modal component a heading, then the title is used to label the dialog element with aria-labelledby. This helps to convey the purpose of the modal to screen reader users when it displays.
Modal purpose and usage
Modals are overlays that require merchants to take an action before they can continue interacting with the rest of Shopify. They can be disruptive and should be used thoughtfully and sparingly. Modals should be thought of as temporary and not be used for information or actions that need to live on in the UI in a persistent way. Don't use modals to display complex forms or large amounts of information.
TextContainer is deprecated
The TextContainer component is deprecated and was made redundant by the BlockStack component. Use BlockStack with gap values of 2, 4, and 5 to replicate TextContainer layouts.
TextContainer spacing options
TextContainer supports three spacing options: default, tight, and loose. Tight spacing relates content topics to each other, while loose spacing separates concepts that are independent of each other. The closer the spacing, the closer the relationship between content topics.
TextContainer use cases
TextContainer is used to wrap text elements such as paragraphs, headings, and lists to give them vertical spacing.
TextContainer released in version
TextContainer was released in version 1.9.0.
VisuallyHidden component is deprecated
The VisuallyHidden component is no longer supported. Users should use the Text component instead with the visuallyHidden prop.
VisuallyHidden purpose
The VisuallyHidden component was used when an element needs to be available to assistive technology such as screen readers but otherwise hidden from visual display.
Migrate VisuallyHidden to Text component
To migrate from VisuallyHidden, replace it with the Text component using the visuallyHidden prop. For example, replace `<VisuallyHidden><Heading>Title and description</Heading></VisuallyHidden>` with `<Text visuallyHidden variant="headingMd" as="h2">Title and description</Text>`.
Toast with action dismissal behavior
Toast should not have actions like [Cancel] for dismissing the toast. The [X] to dismiss is already included in the component.
Toast with action fallback accessibility requirement
Make sure that merchants can also accomplish the action in the toast another way, since the toast action may be difficult to access for some merchants. If the toast action is not available somewhere else on the page, such as a retry action that reloads a section, it should have a fallback action, such as a browser refresh.
Toast accessibility with modal
To ensure that toasts are read out by a screen reader when a modal is open, apps should be wrapped in a Frame component.
Toast component is deprecated
The toast component is no longer supported. Use the App Bridge Toast API instead, available at https://shopify.dev/docs/api/app-bridge-library/reference/toast.
Toast must be wrapped in frame component
The toast component must be wrapped in the frame component.