Examples
Use as the default option for a modal.
Modals are overlays that prevent merchants from interacting with the rest of the application until a specific action is taken. They can be disruptive because they require merchants to take an action before they can continue interacting with the rest of Shopify. It should be used thoughtfully and sparingly.
Use as the default option for a modal.
role=”dialog”
to convey to screen reader users that they work like native dialog windows.title
prop 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.activator
.X
button, the Cancel
button if one is provided, or by pressing the Esc keyUse to let merchants take a key action.
Use to let merchants take key actions at the bottom of the modal.
Use to make it clear to the merchant that the action is potentially dangerous. Only use this option when the merchant is about to perform an action that can’t be undone or is difficult to undo.
See Material Design and development documentation about accessibility for Android:
Use to let merchants take a key action.
Use to let merchants take key actions at the bottom of the modal.
Use to make it clear to the merchant that the action is potentially dangerous. Only use this option when the merchant is about to perform an action that can’t be undone or is difficult to undo.
See Apple’s Human Interface Guidelines and API documentation about accessibility for iOS:
Passing an API key to the app provider component causes the modal component to delegate to the Shopify App Bridge instead of rendering as it would in a stand-alone application.
In an embedded application context, not all documented properties are available. Some properties are only available in stand-alone applications.
Properties that are available only in a stand-alone context are documented as (stand-alone app use only)
. For instance the children
property is documented as (stand-alone app use only)
.
The following example shows the modal component in an embedded application context:
function EmbeddedAppModalExample() {
const [modalOpen, setModalOpen] = useState(false);
const handleModalClose = useCallback(() => setModalOpen(false), []);
return (
<AppProvider apiKey="YOUR_API_KEY" i18n={{}} shopOrigin="YOUR_SHOP_ORIGIN">
<Modal
src="https://my-app.com/upgrade-to-retail-package"
open={modalOpen}
title="Upgrade your Shopify POS with the Retail Package"
primaryAction={{
content: 'Add Retail Package',
onAction: handleModalClose,
}}
secondaryActions={[
{
content: 'Cancel',
onAction: handleModalClose,
},
]}
onClose={handleModalClose}
/>
</AppProvider>
);
}
As of v3.17.0, using Modal
in an embedded app is deprecated. Support for this will be removed in v5.0 as the underlying Shopify App Bridge library will be removed from Polaris React. Learn more about the deprecation rationale. Use Modal
from @shopify/app-bridge-react
instead.
Use modals when merchants must complete an action before they can continue with the main workflow. Avoid using modals to display complex forms or large amounts of information.
Modals should:
X
button, the Cancel
button, or the Esc key, not when merchants click or tap the area outside the modal.Modal titles should:
Edit email address
Delete customer?
Discard unsaved changes?
Edit the email address for this order
Are you sure you want to delete customer?
Discard?
Body content should be:
Notification emails will be sent to this address.
This can’t be undone.
You can edit the email address where emails will be sent.
Are you sure you want to delete the variant Dark Blue Tee/Small/Silk? You cannot reverse this.
To buy a shipping label, you need to enter the total weight of your shipment, including packaging.
To buy a shipping label, you must enter the total weight of your shipment, including packaging.
Actions should be:
Create order
Buy shipping label
New order
Buy
Activate Apple Pay
View shipping settings
Try Apple Pay
View your settings
Add menu item
Add a menu item
Tertiary actions should:
Use a plain button for a tertiary action if needed
Use a tertiary action for a destructive action
Body content should be:
Notification emails will be sent to this address.
You can edit the email address where emails will be sent.
To buy a shipping label, you need to enter the total weight of your shipment, including packaging.
To buy a shipping label, you must enter the total weight of your shipment, including packaging.