Documentation

Modals

Beta

Adaptive modal presentation, dismissal rules, backdrop controls, and overlay suppression behavior for high-attention moments.

Adaptive presentation

Snippettext

Modal presentation:
- Desktop: centered overlay
- Mobile: bottom sheet
- Stored position: TOP_FIXED
- Runtime adapts layout responsively

You do not choose between separate center and sheet templates. SpryUI uses one system modal and adapts its presentation by viewport size.

Default template and tokens

Default modal HTMLhtml

<!-- Supported modal tokens: {{headline}}, {{body}}, {{imageUrl}}, {{imageAlt}}, {{primaryCta.label}}, {{primaryCta.href}} -->
<div class="spry-message spry-modal-backdrop">
  <div class="spry-modal" role="dialog" aria-modal="true">
    <button class="spry-modal__dismiss spry-dismiss" aria-label="Close">
      <span class="bi bi-x"></span>
    </button>

    <div class="spry-modal__media" data-block="image">
      <img src="{{imageUrl}}" alt="{{imageAlt}}" />
    </div>

    <div class="spry-modal__body" data-block="body">
      <h2 class="spry-modal__headline" data-block="headline">{{headline}}</h2>
      <div class="spry-modal__copy">{{body}}</div>
      <div class="spry-modal__actions">
        <a class="spry-modal__cta spry-modal__cta--primary" data-block="primaryCta" href="{{primaryCta.href}}" role="button">
          {{primaryCta.label}}
        </a>
      </div>
    </div>
  </div>
</div>

The default modal supports headline, body HTML, optional media, and a single primary CTA. Empty CTA/image slots collapse cleanly, so the same template works for simple announcements and higher-attention conversion prompts.

Runtime behavior

Snippettext

Modal delivery rules:
- one winning modal can be active at a time
- winning modal suppresses other modals, toasts, and fixed banners
- Escape closes only when dismiss.enabled === true
- outside click closes only when dismiss.enabled === true and clickOutside !== false
- backdrop can be disabled or overridden with color/blur values

The runtime traps focus inside the active modal, locks body scroll, and restores focus when the modal closes.
When dismissal is disabled, close button, Escape, and outside click are all blocked together.
Backdrop tint and blur are optional and can be overridden per modal through content.backdrop.