SModal <s-modal>

Un cuadro de diálogo superpuesto para tareas concretas y confirmaciones, que se abre con un comando o una llamada a un método. SModal es el wrapper de Vue 3 tipado del web component <s-modal> de Shopify Polaris.

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

Buenas prácticas

• Reserva los modales para decisiones que requieren atención. Abre uno cuando los comerciantes deban tomar una decisión concreta o reconocer algo crítico. Si la tarea o la herramienta puede estar directamente en la página, déjala allí.
• Úsalos con moderación. Cada modal interrumpe al comerciante, así que trátalo como un último recurso para los momentos importantes y no como un patrón predeterminado.
• Haz que la acción principal destaque. Dale al modal una única llamada a la acción clara y destacada en el slot primary-action.
• Etiqueta las acciones con verbos específicos. Botones como "Delete", "Save" o "Continue" indican a los comerciantes lo que ocurrirá; evita etiquetas genéricas como "Yes", "OK" o "Submit".
• Explica las consecuencias de las acciones destructivas. Cuando la acción elimina o descarta algo, describe en el cuerpo del modal lo que los comerciantes van a perder.
• No anides modales. Evita abrir un segundo modal desde uno que ya está abierto.

<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>

Consulta las buenas prácticas de Shopify para <s-modal> (en inglés) para ver todas las recomendaciones.

Ejemplo

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	Tipo	Descripción
accessibilityLabel	string	Una etiqueta que describe el propósito del modal. Cuando se define, se anuncia a los usuarios de tecnologías de asistencia y les proporciona más contexto. Para los lectores de pantalla, reemplaza la prop heading.
heading	string	Un título que describe el contenido del modal.
padding	"base" | "none"	Ajusta el relleno alrededor del contenido del modal. base: aplica un relleno adecuado para el elemento. none: elimina todo el relleno del elemento. Puede ser útil cuando los elementos dentro del modal deben extenderse hasta su borde, por ejemplo, una imagen a ancho completo. En ese caso, usa un box con un relleno de 'base' para recuperar el relleno deseado en el resto del contenido.
size	"base" | "small-100" | "small" | "large" | "large-100"	El tamaño del componente modal, que controla su anchura y altura. Los tamaños más grandes ofrecen más espacio para el contenido, mientras que los más pequeños son más compactos.

Events

Event	Tipo
afterhide	CustomEvent
aftershow	CustomEvent
hide	CustomEvent
show	CustomEvent

Escúchalos con listeners del estilo @afterhide en <SModal>.

Methods

<SModal> expone los siguientes métodos en su elemento DOM subyacente (accesibles mediante una template ref tipada):

• hideOverlay() => void — Método para ocultar una superposición.
• showOverlay() => void — Método para mostrar una superposición.
• toggleOverlay() => void — Método para alternar la visibilidad de una superposición.

<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	Descripción
default	El contenido que se muestra dentro del componente de modal, que suele incluir campos de formulario, información o elementos interactivos.
primary-action	El botón de acción principal que se muestra en el pie del modal y que representa la acción principal que deben realizar los usuarios. Solo acepta un único componente button con un variant de primary. Esta acción debe estar alineada con el propósito principal del modal.
secondary-actions	Botones de acción adicionales que se muestran en el pie del modal y ofrecen acciones alternativas o complementarias. Solo acepta componentes de botón con una variant de secondary o auto. Tienen menos énfasis visual para establecer una jerarquía clara.