Modal
The Modal component displays content in an overlay that requires merchant attention. Use modals to present critical information, confirmations, or focused tasks while maintaining page context.
Modals block interaction with the underlying interface until the merchant resolves the modal content.
Modals don't automatically handle state management or persistence, so manage visibility and lifecycle programmatically through events.
Supported targets
- pos.
cart. line-item-details. action. render - pos.
customer-details. action. render - pos.
customer-details. block. render - pos.
draft-order-details. action. render - pos.
draft-order-details. block. render - pos.
exchange. post. action. render - pos.
exchange. post. block. render - pos.
home. modal. render - pos.
order-details. action. render - pos.
order-details. block. render - pos.
product-details. action. render - pos.
product-details. block. render - pos.
purchase. post. action. render - pos.
purchase. post. block. render - pos.
register-details. action. render - pos.
register-details. block. render - pos.
return. post. action. render - pos.
return. post. block. render
Supported targets
- pos.
cart. line-item-details. action. render - pos.
customer-details. action. render - pos.
customer-details. block. render - pos.
draft-order-details. action. render - pos.
draft-order-details. block. render - pos.
exchange. post. action. render - pos.
exchange. post. block. render - pos.
home. modal. render - pos.
order-details. action. render - pos.
order-details. block. render - pos.
product-details. action. render - pos.
product-details. block. render - pos.
purchase. post. action. render - pos.
purchase. post. block. render - pos.
register-details. action. render - pos.
register-details. block. render - pos.
return. post. action. render - pos.
return. post. block. render
Use cases
- Confirmations: Display confirmation dialogs for critical actions like refunds or data deletion.
- Detailed views: Present information requiring focused attention, like error details or status.
- Data collection: Collect input through forms or settings panels without navigating away.
- Progress indicators: Show progress for long-running operations like imports or sync.
Anchor to examplesExamples
Anchor to example-display-content-in-a-modal-overlayDisplay content in a modal overlay
Display focused content in an overlay using a Modal component that requires merchant attention. This example shows a basic modal with header, content area, and action buttons.
Display content in a modal overlay
Display content in a modal overlay
Examples
Display content in a modal overlay
Description
Display focused content in an overlay using a `Modal` component that requires merchant attention. This example shows a basic modal with header, content area, and action buttons.
Default
<s-button command="--show" commandFor="modal"> Open modal </s-button> <s-modal id="modal" heading="Changes could not be saved"> Please check your internet connection and try again. <s-button slot="primary-action">OK</s-button> </s-modal>
Anchor to propertiesProperties
Configure the following properties on the Modal component.
- Anchor to headingheadingheadingstringstring
A title that describes the content of the Modal.
- Anchor to idididstringstring
A unique identifier for the element.
Anchor to slotsSlots
The Modal component supports slots for additional content placement within the modal. Learn more about using slots.
- Anchor to primary-actionprimary-actionprimary-actionHTMLElementHTMLElement
The primary action button displayed in the modal.
The tone of the button is used to define the tone of the modal.
If omitted, the modal will default to an 'info' tone, and show an 'OK' button, translated according to the user's locale.
- Anchor to secondary-actionssecondary-actionssecondary-actionsHTMLElementHTMLElement
The secondary action buttons displayed in the modal.
Anchor to eventsEvents
The Modal component provides event callbacks for handling user interactions. Learn more about handling events.
- Anchor to hidehidehide(event: CallbackEvent<"s-modal">) => void(event: CallbackEvent<"s-modal">) => void
Callback when the modal is hidden.
- Anchor to showshowshow(event: CallbackEvent<"s-modal">) => void(event: CallbackEvent<"s-modal">) => void
Callback when the modal is shown.
CallbackEvent
- bubbles
boolean - cancelable
boolean - composed
boolean - currentTarget
HTMLElementTagNameMap[T] - detail
any - eventPhase
number - target
HTMLElementTagNameMap[T] | null
interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
currentTarget: HTMLElementTagNameMap[T];
bubbles?: boolean;
cancelable?: boolean;
composed?: boolean;
detail?: any;
eventPhase: number;
target: HTMLElementTagNameMap[T] | null;
}Anchor to best-practicesBest practices
- Use for focused interactions: Reserve modals for confirmations, critical information, or tasks requiring immediate attention.
- Write clear headings: Use concise titles that communicate the purpose or action.
- Choose appropriate button tones: The primary-action button's
tonedetermines the modal's overall tone. Usecriticalfor destructive actions,successfor confirmations. - Include secondary actions: Provide options like "Cancel" or "Go Back" to give merchants flexibility.
- Keep content focused: Limit to essential information and actions. For complex workflows, break into multiple steps.
Anchor to limitationsLimitations
Multiple modals can't be displayed simultaneously—showing a new modal while another is visible may cause unexpected behavior or poor user experience.