Alpine.js x-htmldialog Plugin

The Hyvä HTML Dialog is an Alpine.js plugin that enhances the native HTML <dialog> element. It simplifies creating accessible and interactive modals, pop-ups, and off-canvas panels.

It works with Alpine's x-show directive to manage dialog visibility and state.

Usage

To use the x-htmldialog plugin, add the directive to an HTML <dialog> element that is also controlled by x-show.

<div x-data="{ open: false }">
    <button @click="open = !open">Open</button>
    <dialog x-show="open" x-htmldialog="open = false">
        <!-- Dialog content goes here -->
    </dialog>
</div>

When x-htmldialog is used with an x-show element:

• It overrides x-show's default display toggling.
• Instead, it uses the native el.showModal() to display the dialog.
• The optional value (e.g., "open = false") runs when the dialog closes via the Escape key or backdrop click.

Modifiers

Customize x-htmldialog behavior using modifiers.

noscroll

The noscroll modifier prevents background page scrolling when the dialog is open.

<div x-data="{ open: false }">
    <button @click="open = !open">Open</button>
    <dialog x-show="open" x-htmldialog.noscroll="open = false">..</dialog>
</div>

:where(:root:has(dialog[open]:modal)) {
    overflow: hidden;
}

closeby

The closeby option controls how the dialog can be dismissed. The plugin polyfills this behavior for browsers without native support.

Set this option in two ways:

1. As an attribute on the <dialog> element:

<dialog closeby="any" ...>

2. As a modifier on the x-htmldialog directive:

<dialog x-htmldialog.closeby.any ...>

Available Options

• any: Closes on any user action (e.g., ESC key, backdrop click).
• closerequest: (Default) Closes via ESC key or a "close request" (e.g., form submission with method="dialog"). Does not close on backdrop click.
• none: User cannot close the dialog; it must be closed programmatically.

These docs can also be found on the fylgja.dev.