A lightweight web component wrapper for native <dialog> elements with state-driven animations.
- Zero dependencies - Uses native
<dialog>for focus trapping and accessibility - Lightweight - ~3.4kb minified
- State-driven animations - CSS transitions based on
stateattribute - One overlay surface - Always style
<dialog-backdrop>; the same rule holds in every package - Accessible - Native dialog handles focus trap, escape key, and ARIA
- Nested dialogs - Proper stacking and event isolation
npm install @magic-spells/dialog-panel// Import for side effects (registers custom elements)
import '@magic-spells/dialog-panel';Or include directly in HTML:
<script src="https://unpkg.com/@magic-spells/dialog-panel"></script>
<link rel="stylesheet" href="https://unpkg.com/@magic-spells/dialog-panel/css/min" />| File | Format | Use |
|---|---|---|
dist/dialog-panel.esm.js |
ESM | import — bundlers, <script type="module"> |
dist/dialog-panel.js |
UMD | classic <script src>, exposes global DialogPanel |
dist/dialog-panel.min.js |
UMD, minified | what the unpkg URL above resolves to |
dist/dialog-panel.css |
CSS | @magic-spells/dialog-panel/css |
dist/dialog-panel.min.css |
CSS, minified | @magic-spells/dialog-panel/css/min |
2.0.0 drops the CommonJS build. dist/dialog-panel.cjs.js, the main
field, and the require export condition are all gone. Nothing else changed —
the component API, events, attributes, and CSS are identical to 1.3.0.
If you were using require('@magic-spells/dialog-panel'), switch to import.
The plain <script src> CDN snippet is unaffected: the UMD builds are still
published, and window.DialogPanel still works.
<button id="open-btn">Open Dialog</button>
<dialog-panel id="my-dialog">
<dialog aria-labelledby="dialog-title">
<div class="dialog-content">
<h2 id="dialog-title">Hello!</h2>
<p>This is a modal dialog.</p>
<button data-action-hide-dialog>Close</button>
</div>
</dialog>
</dialog-panel>
<script>
const dialog = document.getElementById('my-dialog');
document.getElementById('open-btn').addEventListener('click', (e) => {
dialog.show(e.target);
});
</script>dialog-panel can use a duck-typed @magic-spells/morph-engine instance as
its transition transport without taking a dependency on the engine. Assign the
engine to the writable morphEngine property and pass the source element to
show():
<button id="morph-card">Open details</button>
<dialog-panel id="morph-panel" morph-display="flex">
<dialog>
<h2>Details</h2>
<p>The card springs into this real modal dialog.</p>
<button data-action-hide-dialog>Close</button>
</dialog>
</dialog-panel>
<script>
const panel = document.getElementById('morph-panel');
const card = document.getElementById('morph-card');
panel.morphEngine = new MorphEngine.MorphEngine({
lockScroll: false,
zIndex: 10000000,
});
card.addEventListener('click', () => panel.show(card));
</script>Calling hide() during the outbound flight or show() during the return flight
reverses the active spring in place. Calling show() without a trigger element
uses the existing CSS transition path instead.
When the engine animates a stand-in element in normal flow, the dialog stays
closed for the whole flight and moves into the browser top layer with
showModal() on the spring's settle frame. An engine that reports
animatesDialog animates the real <dialog> in the top layer instead, so the
panel opens it up front and the flight runs on the modal itself. Either kind is
finalized by the engine's own hidden and stop events.
morph-display controls the display value used while measuring and revealing a
closed target (block by default). Assigning an engine automatically adds the
morph attribute as a CSS hook; assigning null removes it. The default
stylesheet uses that hook to pin the target geometry and hand control of
opacity, transforms, and transitions to the engine.
Give morph dialogs an explicit width and height so their in-flow and :modal
geometry match. Consumer CSS must not set opacity, transform, or
transition on the dialog in morph mode because those declarations fight the
engine's inline animation styles.
By default, the panel is centered and uses a fade/scale animation. Set the
position attribute to slide the panel in from an edge instead:
<dialog-panel position="bottom">...</dialog-panel>| Value | Animation | Typical use |
|---|---|---|
center (default) |
Fade + scale | Standard modal |
top |
Slide down from top | Predictive search, notifications |
bottom |
Slide up from bottom | iOS-style action sheets |
left |
Slide in from left | Mobile nav menu |
right |
Slide in from right | Cart drawer, side panel |
Drawer panels default to full width (top/bottom, max-height 85vh) or full
height (left/right, min(24rem, 90vw) wide). Override with your own CSS to
customize:
dialog-panel[position='right'] > dialog {
width: 28rem;
}- Wrap a native
<dialog>element inside<dialog-panel> - Call
show(triggerElement)to open with animation - The
stateattribute transitions:hidden→showing→shown - Close via:
- Clicking backdrop
- Pressing Escape
- Clicking any element with
data-action-hide-dialog - Calling
hide()
- The
stateattribute transitions:shown→hiding→hidden - Focus returns to the trigger element
A dialog can also be closed out from under the panel — by submitting a
<form method="dialog"> inside it, or by calling panel.dialog.close()
directly. There is no exit animation to play in that case, so the panel
skips hiding and settles straight to hidden, firing hidden and
returning focus as usual. beforeHide is not fired: it is cancelable,
and cancelling cannot reopen a dialog the browser has already closed.
The dialog's returnValue — the value of the submit button in a
<form method="dialog"> — is reported as result on the hidden event.
hidden → showing → shown → hiding → hidden
A native close short-circuits that path: shown → hidden.
The state attribute on <dialog-panel> drives all CSS animations:
dialog-panel[state='showing'] > dialog { /* entering */ }
dialog-panel[state='shown'] > dialog { /* fully visible */ }
dialog-panel[state='hiding'] > dialog { /* exiting */ }
dialog-panel[state='hidden'] > dialog { /* hidden */ }| Method | Description |
|---|---|
show(triggerEl?) |
Opens the dialog. Pass trigger element for focus return. Returns false if cancelled. |
hide(triggerEl?) |
Closes the dialog. Returns false if cancelled. |
| Property | Type | Description |
|---|---|---|
morphEngine |
Object | null |
Optional duck-typed morph transport. Set to null to restore CSS-only mode. |
state |
string |
Current state: 'hidden', 'showing', 'shown', 'hiding' |
dialog |
HTMLDialogElement |
Reference to inner <dialog> |
isOpen |
boolean |
true if showing or shown |
triggerElement |
HTMLElement | null |
Element that triggered the current action |
| Event | Cancelable | Description |
|---|---|---|
beforeShow |
Yes | Fired before showing. Call preventDefault() to cancel. |
shown |
No | Fired after show animation completes. |
beforeHide |
Yes | Fired before hiding. Call preventDefault() to cancel. |
hidden |
No | Fired after hide animation completes. |
beforeHide is skipped on a native close — see Native
closes.
Event detail includes:
triggerElement- Element that triggered the actionresult- Value fromdata-resultattribute, or the dialog'sreturnValueon a native close (if any)state- Current state
| Attribute | Description |
|---|---|
data-action-hide-dialog |
Clicking this element closes the dialog |
data-result |
Value passed to hidden event when this element triggers close |
Import the default styles:
import '@magic-spells/dialog-panel';
import '@magic-spells/dialog-panel/css';Or in HTML:
<link rel="stylesheet" href="https://unpkg.com/@magic-spells/dialog-panel/css/min" />| Property | Default | Description |
|---|---|---|
--dialog-backdrop-z-index |
1000 |
Stacking level of <dialog-backdrop>. Raise it only as far as your page's own stacking requires — very large values can cause compositor flicker when showModal() promotes the dialog to the top layer. |
Override styles using the state attribute:
/* Custom backdrop */
dialog-backdrop {
background: rgba(0, 0, 0, 0.5);
backdrop-filter: blur(5px);
}
/* Custom dialog appearance */
dialog-panel > dialog {
border-radius: 1rem;
box-shadow: 0 25px 50px rgba(0, 0, 0, 0.25);
}
/* Custom animations */
dialog-panel[state='shown'] > dialog {
opacity: 1;
transform: scale(1);
transition: all 0.3s ease-out;
}
dialog-panel[state='hiding'] > dialog {
opacity: 0;
transform: scale(0.95);
transition: all 0.2s ease-in;
}Dialogs can be nested inside other dialogs:
<dialog-panel id="outer">
<dialog>
<p>Outer dialog content</p>
<button id="open-inner">Open Inner</button>
<dialog-panel id="inner">
<dialog>
<p>Inner dialog content</p>
<button data-action-hide-dialog>Close Inner</button>
</dialog>
</dialog-panel>
</dialog>
</dialog-panel>Each dialog manages its own backdrop and events independently.
<dialog-backdrop> is the overlay surface. It is auto-created if not present, so it
is always there and you never have to opt in.
Style the overlay here, always. Never style dialog::backdrop — the package keeps the
native pseudo-element transparent on every panel, so anything you paint there is either
invisible or fighting the element. One rule, every panel, every package in the family
(sheet, bottom-sheet, and anything downstream all work the same way).
dialog-backdrop {
background: rgba(0, 0, 0, 0.5);
backdrop-filter: blur(4px) saturate(115%);
}Why an element rather than the native pseudo-element:
- It survives adding a morph transport later. A morph engine flies its blob in normal
flow, so the overlay has to be something the blob can pass above.
::backdroplives in the top layer and would paint over the blob, blurring the very thing in flight. Because the overlay is already an element, attaching a morph engine needs no CSS changes at all. - Click-to-close is built in.
- Consistent animation across browsers, driven by the
stateattribute.
Use beforeHide to prevent closing:
dialog.addEventListener('beforeHide', (e) => {
if (formHasUnsavedChanges) {
e.preventDefault();
showConfirmation();
}
});Track which button closed the dialog:
<button data-action-hide-dialog data-result="save">Save</button>
<button data-action-hide-dialog data-result="cancel">Cancel</button>dialog.addEventListener('hidden', (e) => {
if (e.detail.result === 'save') {
saveData();
}
});Modern browsers with support for:
- Custom Elements v1
- Native
<dialog>element - CSS
:has()selector
MIT