--- title: "Dialog" description: "A window overlaid on the page or on another dialog, rendering the content underneath inert. Built on the native element." url: "https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/dialog" section: "Components" --- # Dialog A window overlaid on the page or on another dialog, rendering the content underneath inert. Built on the native element. ```html

Edit profile

Make changes to your profile here. Click save when you're done.

 ``` ## Markup A dialog is a native `` with `.dialog` and `data-dialog`. Opened as a modal, the browser puts it in the top layer above everything else, makes the rest of the page inert (no clicks, no focus, hidden from screen readers), moves focus into it and returns focus to the button that opened it when it closes. The page behind it stops scrolling. - `.dialog-header` holds `.dialog-title` and `.dialog-description`. Point `aria-labelledby` and `aria-describedby` at them. - `.dialog-content` is an optional body that scrolls on its own, keeping the header and footer in view. - `.dialog-footer` is a row of actions: stacked on small screens with the last button on top, right-aligned from the `sm` breakpoint. - `.dialog-close` is the corner close button. It is optional. The same behaviour drives the [sheet](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/sheet), a dialog that slides in from an edge of the screen, and the [drawer](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/drawer), one that can also be swiped away. ## Opening and closing Open it with an [invoker command](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/button#command): a button with `commandfor=""` and `command="show-modal"`. Browsers with invoker commands need no script for it; for the rest, the dialog behaviour handles the click. From script, call `dialog.showModal()`. It closes on any of these: - `Esc`. - A click outside it, on the backdrop. (Not for an [alert dialog](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/alert-dialog).) - A click on any element inside with `data-dialog-close`. Its value, or the button's `value`, becomes `dialog.returnValue`. - Submitting a `
` inside it (no JavaScript). The submit button's `value` becomes `returnValue`. - A button with `commandfor` and `command="close"`. Each fires the native `close` event on the ``, so `hx-trigger="close"` on it, or a listener reading `returnValue`, can act on the answer. ## No close button Leave out `.dialog-close` for a dialog that closes only with `Esc` or a click outside. ```html

No close button

This dialog has no close button. Press Escape or click outside to close it.

 ``` ## Custom close button Any element with `data-dialog-close` closes the dialog it is in, so the footer's own button can do it. ```html
``` ## Scrollable content Long content scrolls inside `.dialog-content` while the header stays in view. A dialog is never taller than the viewport less a margin; give it a `max-h-*` to cap it lower. ```html

Scrollable content

This is a dialog with scrollable content.

Pages are plain HTML rendered by Nunjucks at build time. Components are CSS classes, with a small behaviour where one is needed.

htmx swaps fragments from your server into the page. Components inside a fragment initialise as soon as it arrives, so a dialog returned by a request works like one written in the page.

Every colour is a CSS variable. Override the tokens on :root, or on any element, to theme the whole library, in light and dark.

The native dialog element does the hard parts: the top layer, an inert page underneath, focus moving in and coming back, and Escape.

Dialogs can open over other dialogs. Each new one stacks on top with its own backdrop, and Escape closes the topmost first.

A form inside a dialog can post with htmx. The server answers with a fragment for the page and closes the dialog with a response header.

Alert dialogs are the same element with role="alertdialog". They don't close on a click outside, because they need an answer.

Without JavaScript, a form with method="dialog" still closes it, and browsers with invoker commands still open it.

 ``` ## Sticky footer With a `.dialog-content` between them, the footer stays visible while the content scrolls. `.dialog-footer-sticky` sets it apart: tinted, edge to edge, with a border on top. ```html

Terms of service

Please read and accept the terms to continue.

1. Acceptance. By using the service you agree to these terms. If you don't agree, don't use it.

2. Accounts. You are responsible for your account and for everything done with it. Keep your password safe.

3. Content. You keep the rights to what you upload. You give us the permission we need to store and show it to the people you share it with.

4. Acceptable use. Don't break the law, don't attack the service, and don't use it to harm other people.

5. Payment. Paid plans are billed in advance and renew until you cancel. Cancelling stops the next renewal.

6. Termination. You can stop using the service at any time. We may suspend accounts that break these terms.

7. Changes. We will tell you before these terms change. Using the service after a change means you accept it.

 ``` ## Sizes A dialog is `max-w-lg` wide. `.dialog-sm`, `.dialog-lg` and `.dialog-xl` change that, or use any `max-w-*` utility. ```html

Small dialog

.dialog-sm is max-w-sm.

Extra large dialog

.dialog-xl is max-w-4xl.

 ``` ## Dialog over a dialog A button inside one dialog can open another. It stacks on top with its own backdrop, the first dialog becomes inert, and `Esc` or a click outside closes the topmost one first. ```html

Settings

Manage your workspace.

Are you sure?

This is a second dialog, over the first.

 ``` ## With htmx ### A dialog from the server A dialog can come from the server instead of the page. `data-dialog-show` opens it as a modal as soon as htmx inserts it, and `data-dialog-remove` takes it out of the page again once it has closed, so every click loads a fresh one. Append it to the body: ```html ``` The server returns: ```html

Rename project

 ``` ### Closing it from the server A `dialog:close` event dispatched inside a dialog closes it. htmx dispatches the events named in an `HX-Trigger` response header on the element that made the request, so a server that has saved the form closes the dialog it came from with one header, while the response body goes to the form's `hx-target`. On a validation error, leave the header off and return the form with its messages instead. ```text HTTP/1.1 200 OK Content-Type: text/html; charset=utf-8 HX-Trigger: dialog:close Renamed to htmx-ui ``` ## Macro `dialog()` writes the ``, its header and the close button, with the ids and ARIA attributes wired up. The call body is everything after the header. ```jinja {% from "components/dialog/dialog.html" import dialog %} {% call dialog("invite", "Invite people", "They will get an email with a link.", size="sm") %}
{% endcall %} ``` | Parameter | Description | | --- | --- | | `id` | Required. The id buttons point commandfor at; also prefixes the title and description ids. | | `title, description` | Header text. Each sets aria-labelledby / aria-describedby. | | `close=true` | The corner close button. false leaves it out. | | `alert=false` | true makes it an alert dialog: role="alertdialog", no corner button, no closing on a click outside. | | `size` | "sm", "lg" or "xl". | | `media, media_variant` | An icon name shown above the title, and "danger" to tint it. | | `show, remove` | data-dialog-show and data-dialog-remove, for dialogs returned by htmx. | | `class` | More classes on the . | ## Accessibility - Give every dialog a name: `aria-labelledby` pointing at its title, or `aria-label`. - Focus moves to the first focusable element inside, or to one marked `autofocus`. Put `autofocus` on the field the user needs first, or on the safest button. - An icon-only close button needs an `aria-label`. - Use an [alert dialog](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/alert-dialog) when the user must answer before going on. ## Reference | Class | Description | | --- | --- | | `.dialog` | The : centred, padded, scrolls when taller than the viewport. Fades and zooms in and out. | | `.dialog-header / .dialog-title / .dialog-description` | Title block, centred on small screens. | | `.dialog-content` | Body that scrolls on its own, keeping the header and footer in view. | | `.dialog-footer` | Actions: stacked on small screens, a right-aligned row from sm. | | `.dialog-footer-sticky` | Tinted, edge-to-edge footer with a top border. | | `.dialog-close` | Corner close button. | | `.dialog-sm / -lg / -xl` | Widths: max-w-sm, max-w-2xl, max-w-4xl (default max-w-lg). | | `.dialog-media / .dialog-media-danger` | An icon or image above the title; see Alert dialog. | | `[data-dialog]` | Behaviour: closes on a click outside and on [data-dialog-close], opens command buttons in older browsers. | | `[data-dialog-close="value"]` | Closes the dialog it is in; the value becomes returnValue. | | `[data-dialog-show] / [data-dialog-remove]` | Open as a modal when initialised / remove from the page once closed. | | `dialog:close event` | Closes the dialog it is dispatched in, e.g. from an HX-Trigger response header. |