The modal component wraps the native <dialog> element with animated open/close, backdrop blur, scroll locking, and a declarative slot system for header, body, and footer. Add data-wf-modal to any <dialog> and the JS scaffolds the structure automatically. wf-action-modal extends this for server-driven AJAX workflows.
Add data-wf-modal and data-wf-label to the dialog. JS builds the header, body, and close button automatically. A trigger element uses data-wf-open pointing to the dialog's id .
<!-- Trigger -->
<button class="wf-btn wf-btn-primary" data-wf-open="my-modal" type="button">Open Modal</button>
<!-- Dialog -->
<dialog id="my-modal" class="wf-modal" data-wf-modal data-wf-label="Basic Modal">
<p>Modal content goes here.</p>
</dialog>Set data-wf-size on the dialog to choose a panel width: sm (22rem), default md (32rem), lg (48rem), xl (64rem), or full (viewport width).
<dialog class="wf-modal" data-wf-modal data-wf-label="Small" data-wf-size="sm">...</dialog>
<dialog class="wf-modal" data-wf-modal data-wf-label="Default">...</dialog>
<dialog class="wf-modal" data-wf-modal data-wf-label="Large" data-wf-size="lg">...</dialog>
<dialog class="wf-modal" data-wf-modal data-wf-label="Extra Large" data-wf-size="xl">...</dialog>
<dialog class="wf-modal" data-wf-modal data-wf-label="Full" data-wf-size="full">...</dialog>Omit the header and close the button entirely. Your content controls its own 'dismiss UI'.
<dialog class="wf-modal" data-wf-modal data-wf-without-header>
<p>Content…</p>
<button class="wf-btn wf-btn-primary" data-wf-close type="button">
Got it
</button>
</dialog>Click anywhere on the blurred backdrop to close the modal without using the close button.
<dialog class="wf-modal" data-wf-modal
data-wf-label="Light Dismiss"
data-wf-light-dismiss>
<p>Click the backdrop to dismiss.</p>
</dialog>Add a child with data-wf-slot="header-actions" to insert extra buttons into the header – between the title and the close button.
<dialog class="wf-modal" data-wf-modal data-wf-label="Settings">
<p>Content…</p>
<div data-wf-slot="header-actions">
<button class="wf-btn wf-btn-plain wf-btn-icon wf-btn-sm" type="button" title="Help">
<i class="icon help circle" aria-hidden="true"></i>
</button>
</div>
<div data-wf-slot="footer">
<button class="wf-btn wf-btn-plain" data-wf-close type="button">Cancel</button>
<button class="wf-btn wf-btn-primary" type="button">Save</button>
</div>
</dialog>Use data-wf-animation-in and data-wf-animation-out to swap the panel animation. The default is wf-ani-scale-in / wf-ani-scale-out .
<dialog class="wf-modal" data-wf-modal
data-wf-label="Slide"
data-wf-animation-in="wf-ani-slide-up-in"
data-wf-animation-out="wf-ani-slide-down-out">
...
</dialog>
<dialog class="wf-modal" data-wf-modal
data-wf-label="Fade"
data-wf-animation-in="wf-ani-fade-in"
data-wf-animation-out="wf-ani-fade-out">
...
</dialog>Listen for wf:hide and call event.preventDefault() to block closing. The modal will pulse (shake animation) to give the user feedback. Check event.detail.source to allow specific sources to bypass the guard.
document.getElementById('edit-modal').addEventListener('wf:hide', e => {
const isDirty = document.querySelector('#edit-form').dataset.dirty === '1'
if (!isDirty) return
// Allow the confirm button to bypass the guard
if (e.detail.source?.matches('[data-action="confirm-close"]')) return
e.preventDefault() // Blocks close - modal pulses instead
})| Attribute | Element | Description |
|---|---|---|
| data-wf-modal | dialog | Required. Marks the element as a WF modal and triggers auto-init. |
| data-wf-label="Title" | dialog | Header title text rendered by the scaffold. |
| data-wf-size="sm|md|lg|xl|full" | dialog | Width preset applied to the panel. Default: md . |
| data-wf-light-dismiss | dialog | Close the modal when the user clicks the backdrop. |
| data-wf-without-header | dialog | Omit the header entirely – no title, no close button. |
| data-wf-show-duration="250" | dialog | Open animation duration in milliseconds. Default: 200 . |
| data-wf-hide-duration="200" | dialog | Close animation duration in milliseconds. Default: 200 . |
| data-wf-animation-in="wf-ani-*" | dialog | Open animation class from wf-transitions.css . Default: wf-ani-scale-in . |
| data-wf-animation-out="wf-ani-*" | dialog | Close animation class. Default: wf-ani-scale-out . |
| data-wf-i18n-close-label="..." | dialog | Per-instance override for the close button aria-label . |
| data-wf-open="modal-id" | Trigger | On any element – opens the modal matching the given id on click. |
| data-wf-close | Inside modal | Closes the containing modal when clicked. |
| data-wf-slot="footer" | Inside modal | Marks a child element as the footer slot – moved to wf-modal__footer by JS. |
| data-wf-slot="header-actions" | Inside modal | Marks a child as the header-actions slot – inserted into the header before the close button. |
| Property | Default | Description |
|---|---|---|
| --wf-modal-width | 32rem | Override the panel width directly. Set on wf-modal__panel or a parent. |
| --wf-modal-spacing | var(--wf-space-4) | Padding inside the header and footer bars. |
| --wf-anim-duration | Set by JS | Animation duration written by JS on open/close. Controls both panel and backdrop timing. |
All events are dispatched on the <dialog> element and bubble up. wf:show and wf:hide are cancelable.
| Event | Cancelable | Description |
|---|---|---|
| wf:show | Yes | Fired when open() is called. Call event.preventDefault() to block opening. |
| wf:after-show | No | Fired after the open animation completes. |
| wf:hide | Yes | Fired when close is requested. event.detail.source is the triggering element or string. Canceling blocks closing and shakes the modal. |
| wf:after-hide | No | Fired after the close animation completes. event.detail.source available. |
import { WojoModal } from './src/js/components/wf-modal.js'
// Programmatic init and control
const modal = new WojoModal(document.getElementById('my-modal')).init()
modal.open() // Open with animation. Fires wf:show → wf:after-show.
modal.close() // Close with animation. Fires wf:hide → wf:after-hide.
modal.destroy() // Remove listeners and deregister instance.
// Event listeners
document.getElementById('my-modal').addEventListener('wf:show', e => {
console.log('Modal is about to open')
})
document.getElementById('my-modal').addEventListener('wf:hide', e => {
if (hasUnsavedChanges) {
e.preventDefault() // Blocks close, pulses the modal instead
}
})All modifier classes available on .wf-modal
| Class Name | Type | Description |
|---|---|---|
| wf-modal | Base | Applied to the <dialog> . Full-viewport transparent flex container – never animate directly. |
| wf-modal__panel | Child | The visible animated box. Auto-created by JS. Receives animation classes from wf-transitions.css . |
| wf-modal__header / __title / __close / __header-actions | Children | Header bar elements: title text, close button, and optional extra actions slot. |
| wf-modal__body | Child | Scrollable content area. Fills remaining height with overflow-y: auto . |
| wf-modal__footer | Child | Footer bar, right-aligned by default. |
| wf-modal__footer-start / wf-modal__footer-spread | Modifier | Override footer alignment: left-align or space-between. |
| wf-modal-sm / -lg / -xl / -full | Size | Width presets on wf-modal__panel : sm (22rem), default (32rem), lg (48rem), xl (64rem), full (viewport). |