SModal <s-modal>

A dialog overlay for focused tasks and confirmations, opened by a command or a method call. SModal is the typed Vue 3 wrapper for Shopify's Polaris <s-modal> web component.

import { SModal } from 'polaris-vue-elements'

Best practices

• Reserve modals for decisions that need focus. Open one when merchants must make a specific choice or acknowledge something critical. If the task or tool could live directly on the page, keep it there instead.
• Use them sparingly. Every modal interrupts the merchant, so treat it as a last resort for important moments rather than a default pattern.
• Make the main action stand out. Give the modal one clear, prominent call to action in the primary-action slot.
• Label actions with specific verbs. Buttons like "Delete", "Save" or "Continue" tell merchants what will happen; avoid generic labels such as "Yes", "OK" or "Submit".
• Spell out the consequences of destructive actions. When the action deletes or discards something, describe in the modal body what merchants will lose.
• Don't nest modals. Avoid opening a second modal from inside one that is already open.

<SModal id="delete-product" heading="Delete product?">
  <SParagraph>This permanently deletes the product and its variants. You can't undo this.</SParagraph>
  <SButton slot="primary-action" tone="critical">Delete product</SButton>
  <SButton slot="secondary-actions">Cancel</SButton>
</SModal>

See Shopify's best practices for <s-modal> for the full guidance.

Example

Open modal

Modal body content goes here.

SaveCancel

<script setup>
import { SButton, SModal } from 'polaris-vue-elements'
</script>

<template>
  <SButton commandFor="example-modal" command="--show">Open modal</SButton>

  <SModal id="example-modal" heading="Example modal">
    <p>Modal body content goes here.</p>

    <!-- The runtime only accepts a primary-action button with variant="primary",
         and secondary-actions buttons with variant="secondary" (or "auto"). -->
    <template #primary-action>
      <SButton variant="primary">Save</SButton>
    </template>
    <template #secondary-actions>
      <SButton variant="secondary">Cancel</SButton>
    </template>
  </SModal>
</template>

Props

Prop	Type	Description
accessibilityLabel	string	A label that describes the purpose of the modal. When set, it will be announced to users using assistive technologies and will provide them with more context. This overrides the heading prop for screen readers.
heading	string	A title that describes the content of the modal.
padding	"base" | "none"	Adjust the padding around the modal content. base: applies padding that is appropriate for the element. none: removes all padding from the element. This can be useful when elements inside the modal need to span to the edge of the modal. For example, a full-width image. In this case, rely on box with a padding of 'base' to bring back the desired padding for the rest of the content.
size	"base" | "small-100" | "small" | "large" | "large-100"	The size of the modal component, controlling its width and height. Larger sizes provide more space for content while smaller sizes are more compact.

Events

Event	Type
afterhide	CustomEvent
aftershow	CustomEvent
hide	CustomEvent
show	CustomEvent

Listen for these with @afterhide-style listeners on <SModal>.

Methods

<SModal> exposes the following methods on its underlying DOM element (accessible via a typed template ref):

• hideOverlay() => void — Method to hide an overlay.
• showOverlay() => void — Method to show an overlay.
• toggleOverlay() => void — Method to toggle the visiblity of an overlay.

<script setup>
import { useTemplateRef } from 'vue'
import { SModal } from 'polaris-vue-elements'

const modal = useTemplateRef<InstanceType<typeof SModal>>('modal')

function callHideOverlay() {
  modal.value?.$el.hideOverlay()
}
</script>

<template>
  <SModal ref="modal" />
</template>

Slots

Slot	Description
default	The content displayed within the modal component, typically including form fields, information, or interactive elements.
primary-action	The main action button displayed in the modal footer, representing the primary action users should take. Only accepts a single button component with a variant of primary. This action should align with the modal's main purpose.
secondary-actions	Additional action buttons displayed in the modal footer, providing alternative or supporting actions. Only accepts button components with a variant of secondary or auto. These are visually de-emphasized to establish clear hierarchy.