Modal

Dialog component for focused interactions on top of the current page, with focus trapping, scroll locking, and background inerting.

Use when you need a dialog for a focused interaction over the page, with focus trapping, scroll locking, and background inerting. Drive <r-modal> via the open attribute or the imperative Modal.confirm / Modal.info helpers.

Quick Start

Basic Usage

Modal visibility is controlled by the open attribute (or the open property). It starts closed and renders nothing until opened, so wire a trigger to toggle it.

<r-button onclick="modal.open = true">Open Modal</r-button>

<r-modal id="modal" heading="Basic Modal">
  <p>This is the modal content.</p>
  <div slot="footer">
    <r-button type="primary" onclick="modal.open = false">OK</r-button>
  </div>
</r-modal>

API Reference

Properties

closing is a read-only attribute the element reflects on itself (not a settable property): present from the moment close() runs until the mask/dialog's fade-and-scale-out transition actually finishes (~0.3s later, same timing as the afterclose event). Useful for a host page that needs the modal to still count as "present" through that visual tail; see Best Practices below.

Title title

<r-modal open heading="Delete item">
  <p>Are you sure you want to delete this item?</p>
</r-modal>

Closable closable

Hides the header close button so the modal can only be dismissed through your own controls.

<r-modal open heading="Terms" closable="false">
  <p>You must accept the terms to continue.</p>
  <div slot="footer">
    <r-button type="primary">Accept</r-button>
  </div>
</r-modal>

Mask Closable maskClosable

By default clicking the backdrop closes the modal. Set to false to require an explicit action.

<r-modal open heading="Unsaved changes" maskClosable="false">
  <p>Clicking outside will not dismiss this dialog.</p>
</r-modal>

Close on Escape closeOnEsc

<r-modal open heading="Report" closeOnEsc="false">
  <p>The Escape key is disabled for this dialog.</p>
</r-modal>

Lock Scroll lockScroll

<r-modal open heading="Preview" lockScroll="false">
  <p>The page behind the modal can still scroll.</p>
</r-modal>

Auto Focus autoFocus

<r-modal open heading="Search" autoFocus="false">
  <input type="text" placeholder="Type to search" />
</r-modal>

Headerless Mode hideHeader

Drops the title bar and its border entirely, leaving only a floating close button (top-right) when closable. Suited to content-only dialogs like image or diagram lightboxes, where a title bar would just eat into the content. The dialog keeps an accessible name via aria-label (derived from title) even though the visible <h3> title is gone, so set title for a screen-reader label even in headerless mode.

<r-modal open hide-header>
  <img src="/diagram.png" alt="Architecture diagram" style="display: block; max-width: 100%;" />
</r-modal>

Slots

<r-modal open heading="Confirm">
  <p>Body content goes in the default slot.</p>
  <div slot="footer">
    <r-button onclick="modal.open = false">Cancel</r-button>
    <r-button type="primary">Confirm</r-button>
  </div>
</r-modal>

Events

All close-related events carry a trigger in event.detail describing what caused the close: 'mask', 'button', 'escape', or 'program'.

<r-modal id="modal" heading="Example"></r-modal>

<script>
  const modal = document.getElementById('modal');

  modal.addEventListener('beforeclose', (e) => {
    if (!confirm('Discard changes?')) e.preventDefault();
  });

  modal.addEventListener('close', (e) => {
    console.log('closed via', e.detail.trigger); // 'mask' | 'button' | 'escape' | 'program'
  });
</script>

Programmatic API

The Modal class exposes static helpers that create, mount, and resolve a modal without markup. Each returns a Promise<{ action, trigger }> where action is 'confirm', 'cancel', or 'dismiss'.

Options (all optional): title, content, okText, cancelText, showCancel, maskClosable, closeOnEsc, lockScroll, autoFocus, closable, onConfirm, onCancel. onConfirm / onCancel may return false (or a promise resolving to false) to keep the modal open.

import { Modal } from 'ranui/modal';

const result = await Modal.confirm({
  title: 'Delete project',
  content: 'This action cannot be undone.',
  okText: 'Delete',
  cancelText: 'Keep',
  onConfirm: async () => {
    await deleteProject();
  },
});

if (result.action === 'confirm') {
  // deleted
}

CSS Parts

Style internal pieces with ::part().

r-modal::part(dialog) {
  border-radius: 8px;
}
r-modal::part(mask) {
  background: rgba(0, 0, 0, 0.6);
}

Styling

<r-modal> exposes 23 CSS custom properties of its own, plus the semantic tokens it reads from the theme. Set one anywhere it inherits from, such as :root, a wrapper, or the element:

r-modal {
  --ran-modal-mask-background: var(--ran-color-bg-subtle);
}

Parts: body · close · dialog · footer · header · mask · root · title

The full list is in style tokens; which token to use is in the design system.

Best Practices

• Trigger + toggle: Open with modal.open = true and close with modal.open = false, or call close().
• Guard destructive closes: Listen for beforeclose and preventDefault() to confirm before dismissing unsaved work.
• Footer actions: Put primary/secondary buttons in slot="footer"; the footer bar only appears when the slot has content.
• Non-dismissible flows: Set closable="false" and maskClosable="false" to force an explicit choice.
• One-off dialogs: Use Modal.confirm / Modal.info for quick prompts instead of authoring markup.
• Escalating a host page above the modal while it's open: match :has(r-modal[open]), :has(r-modal[closing]), not just [open]. open is removed the instant close() runs, but the mask/dialog transition keeps painting for ~0.3s more; dropping a z-index escalation mid-fade lets the still-visible mask repaint under whatever it was lifted above.