1. Docs
2. Erste Schritte
3. Modal

Modal 1.2.0

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

Wann verwenden

• 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 Fokus trap, Escape, and inert stacking stay consistent.

Wann nicht verwenden

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

Einfaches Modal

Öffnen with open() or the open attribute. Set the sichtbar title with title (HTML-escaped). Standard 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>

Barrierefreiheit

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

Dark Mode, Responsivität, Bewegung, RTL

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

API

Attribut

Slots & parts

Methoden & events

CSS-Variablen

Best practices & pitfalls

• Call open() / close() (or toggle open) — do not invent a size or heading attribute; they are not in the Komponente.
• Always provide a clear title or aria-label for assistive tech.
• Listen for velin-close, not a Komponente-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.
• Attribut bridge: velin-modal on a plain element can bridge to <velin-modal> via the runtime attribute registry — prefer the custom element in new code.

Verwandt

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