1. Docs
2. Components
3. Overlays
4. Modal

Modal 1.2.2

<velin-modal> is a centered dialog overlay with header, body, and optional footer slot. In 1.2.0, open/close lifecycle uses focus-manager for background inert and body scroll lock. Deutsch: Modal De

When to use

• Blocking tasks that need a titled panel (forms, details, multi-step confirmations with custom UI).
• Content that benefits from a footer slot for primary/secondary actions.
• Prefer <velin-modal> over ad-hoc fixed overlays so focus trap, Escape, and inert stacking stay consistent.

When not

• Simple alert / confirm / prompt — use <velin-dialog> (promise API + native <dialog>).
• Non-blocking tips — use Tooltip or Popover.
• Side navigation or filters — use Drawer or Sheet.

Basic modal

Open with open() or the open attribute. Set the visible title with title (HTML-escaped). Default slot is the body; use slot="footer" for actions.

<button type="button" class="velin-btn velin-btn--primary"
        onclick="document.getElementById('myModal').open()">
  Open Modal
</button>

<velin-modal id="myModal" title="Modal title">
  <p>This is a basic modal body.</p>
  <button type="button" class="velin-btn velin-btn--primary" slot="footer"
          onclick="document.getElementById('myModal').close()">Done</button>
</velin-modal>

Footer slot

Place action buttons in the named footer slot. They render in the dialog footer bar.

<velin-modal id="confirmUi" title="Save changes?">
  <p>Unsaved edits will be lost if you leave.</p>
  <button type="button" class="velin-btn velin-btn--outline" slot="footer"
          onclick="this.closest('velin-modal').close()">Cancel</button>
  <button type="button" class="velin-btn velin-btn--primary" slot="footer">Save</button>
</velin-modal>

Accessibility

• Inner panel: role="dialog", aria-modal="true".
• With title: labelled via aria-labelledby. Without title: uses aria-label (attribute or default "Dialog"); title node is visually hidden.
• Built-in close control: aria-label="Close" (part="close").
• On open: focus-manager saves focus, sets sibling inert, locks body overflow; focus moves to the first focusable in the shadow tree.
• Tab / Shift+Tab trap inside the shadow root; Escape calls close().
• On close / disconnect: clears inert + scroll lock for this host and restores previous focus.
• close() dispatches bubbling velin-close.
• Backdrop click (overlay target only) closes the modal.

Dark, responsive, motion, RTL

• Dark / themes: surfaces use --velin-color-surface-bright, borders, and text tokens — follow the active theme.
• Responsive: dialog width is min(90vw, 32rem); max height 85vh with a scrollable body.
• Motion: overlay and dialog transitions are disabled under prefers-reduced-motion: reduce.
• RTL: layout uses logical padding/sizing; no side-specific transform.

API

Attributes

Slots & parts

Methods & events

CSS variables

Best practices & pitfalls

• Call open() / close() (or toggle open) — do not invent a size or heading attribute; they are not in the component.
• Always provide a clear title or aria-label for assistive tech.
• Listen for velin-close, not a component-prefixed close event.
• Stacking is supported: each host registers its own inert layer; removing an open modal from the DOM still clears inert/overflow for that host.
• Attribute bridge: velin-modal on a plain element can bridge to <velin-modal> via the runtime attribute registry — prefer the custom element in new code.

Related

• Dialog — promise-based alert / confirm / prompt
• Drawer — off-canvas panel
• Sheet — bottom sheet
• Lightbox — media gallery overlay