← Web Components

Web Components · Global

<mmm-dialog>

Accessible modal primitive. Backdrop, animation, sizing, focus trap, keyboard close, auto-open with delay, dismiss-once-per-session — all configurable via attributes. Register with dialog-id and open / close from anywhere via window.MmmDialogRegistry[id].

Overview

Every dialog with a dialog-id registers itself on window.MmmDialogRegistry so you can .show() or .hide() it from any script. auto-open + auto-open-delay handle "open after N ms" promo modals; dismiss-once + dismiss-duration remember the dismissal in localStorage so visitors don't see it again for N days.

When to use

  • Welcome / newsletter signup modals (auto-open + dismiss-once).
  • Confirmation prompts (Cancel order, Delete address).
  • Inline auth (drop <mmm-login> inside).
  • Image / video lightboxes (fullscreen="true").

Quick start

<script src="https://v2-api-production.commmerce.com/api/v1/web-component/commmerce-sdk.js?store=sample-store"></script>

<mmm-dialog dialog-id="welcome" auto-open="true" auto-open-delay="3000" dismiss-once="true" dismiss-duration="7">
  <h2>Welcome!</h2>
  <p>Sign up for 10% off your first order.</p>
</mmm-dialog>

Attributes

AttributeTypeDefaultDescription
dialog-idstring—Registry key. Required if you want to open / close imperatively.
backdropbooleantrueRender the dimmed backdrop behind the dialog.
close-on-backdropbooleantrueClicking the backdrop closes the dialog.
animationstringfadeOpen / close animation — fade, slide-up, scale, or none.
sizestring—Preset sizing — sm (18.75rem), default (31.25rem), lg (50rem), xl (71.25rem). Overrides max-width.
max-widthstring37.5remContainer max width when size is unset.
max-heightstring90vhContainer max height.
fullscreenstringnevernever, always, or below-sm / below-md / below-lg / below-xl / below-xxl.
positionstringcenterVertical position — top, center, or bottom.
scrollablebooleanfalseAllow vertical scrolling inside the dialog body when content overflows.
keyboardbooleantrueClose on Esc.
focus-trapbooleantrueTrap keyboard focus inside the dialog while open (accessibility).
z-indexnumber9999Stacking context.
show-close-buttonbooleantrueRender the close button (×).
close-iconstringcrosscross, x-thin, x-bold, circle-x, arrow-left, chevron-left, minus, close-text, custom-text, or custom-image.
close-icon-colorstring#ffffffClose-icon colour.
close-icon-bgstringrgba(0, 0, 0, 0.6)Close-icon background.
close-icon-sizestring2remClose-icon size.
close-icon-positionstringtop-righttop-right, top-left, bottom-right, or bottom-left.
close-icon-border-radiusstring50%Border-radius on the close-icon hit area.
close-icon-customstring—Custom text (for close-text / custom-text) or image URL (for custom-image).
border-radiusstring0.75remDialog border-radius.
loadingbooleanfalseRender a loading overlay over the body.
auto-openbooleanfalseOpen automatically when the element connects.
auto-open-delaynumber0Delay in milliseconds before auto-open.
dismiss-oncebooleanfalseRemember the dismissal — don't reopen for the duration set by dismiss-duration.
dismiss-durationstringsessionsession (sessionStorage), forever (localStorage), or a number of days.

Events

EventTargetPayload
commmerce:dialog-openelement (bubbles, composed){ dialogId }
commmerce:dialog-closeelement (bubbles, composed){ dialogId }
commmerce:dialog-hide-preventedelement (bubbles, composed){ dialogId, reason: 'backdrop' | 'keyboard' }

Live preview

store sample-store tag <mmm-dialog>

Examples

1. Welcome promo, dismiss for a week

<mmm-dialog dialog-id="welcome" size="md" auto-open="true" auto-open-delay="3000" dismiss-once="true" dismiss-duration="7">
  <h2>Welcome!</h2>
  <p>Get 10% off your first order.</p>
  <mmm-footer-newsletter></mmm-footer-newsletter>
</mmm-dialog>

2. Open / close imperatively

const dialog = window.MmmDialogRegistry['welcome'];
dialog.show();
/* … later …  */
dialog.hide();

3. Sticky bottom-sheet on mobile

<mmm-dialog
  dialog-id="cookies"
  size="full"
  position="bottom"
  close-on-backdrop="false"
  backdrop="false"
  show-close-button="false">
  <p>We use cookies. By browsing you accept our policy.</p>
  <button onclick="MmmDialogRegistry.cookies.hide()">Accept</button>
</mmm-dialog>

4. Track open / close

document.addEventListener('commmerce:dialog-open', (e) =>
  analytics.track('dialog_open', { id: e.detail.dialogId })
);
document.addEventListener('commmerce:dialog-close', (e) =>
  analytics.track('dialog_close', { id: e.detail.dialogId, reason: e.detail.reason })
);