Search docs

Dialog

A modal window that asks the user for input or a decision.

Dialog follows the Dialog (Modal) WAI-ARIA design pattern.

Edit profile

Change how your name appears to others.

import { component$, useStyles$ } from '@builder.io/qwik';
import { Dialog } from '@leve-ui/dialog';
import { LuX } from '@qwikest/icons/lucide';
import styles from './default.css?inline';

export default component$(() => {
  useStyles$(styles);

  return (
    <Dialog.Root class="dialog-default">
      <Dialog.Trigger class="dialog-default-trigger">Edit profile</Dialog.Trigger>
      <Dialog.Content class="dialog-default-content">
        <Dialog.Title class="dialog-default-title">Edit profile</Dialog.Title>
        <Dialog.Description class="dialog-default-description">
          Change how your name appears to others.
        </Dialog.Description>
        <label class="dialog-default-label">
          Name
          <input class="dialog-default-input" name="name" value="Ada Lovelace" />
        </label>
        <div class="dialog-default-actions">
          <Dialog.Close class="dialog-default-button">Cancel</Dialog.Close>
          <Dialog.Close class="dialog-default-button dialog-default-button-primary">
            Save
          </Dialog.Close>
        </div>
        <Dialog.Close class="dialog-default-close" aria-label="Close">
          <LuX class="dialog-default-icon" aria-hidden="true" />
        </Dialog.Close>
      </Dialog.Content>
    </Dialog.Root>
  );
});

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/dialog

Anatomy#

import { Dialog } from '@leve-ui/dialog'; // or '@leve-ui/core'

<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Content>
    <Dialog.Title />
    <Dialog.Description />
    <Dialog.Close />
  </Dialog.Content>
</Dialog.Root>
PartElementDescription
Dialog.Root<div>Wraps the parts and holds the open state.
Dialog.Trigger<button>The button that opens the dialog. Use as to render another element or component.
Dialog.Content<dialog>The dialog, opened with showModal().
Dialog.Title<h2>The title that names the dialog.
Dialog.Description<p>The description of the dialog.
Dialog.Close<button>A button that closes the dialog. Use as to render another element or component.

A component passed to as on Dialog.Trigger or Dialog.Close must spread the props it receives onto a single element, including id, aria-*, data-*, and on*$ event handlers.

Dialog.Content is a native <dialog>. It is rendered where you place it, and the browser shows it above the page in the top layer, so overflow: hidden and z-index of its ancestors do not clip it. There is no Overlay part: style the backdrop with the ::backdrop pseudo-element of the Content.

[data-leve-dialog-content]::backdrop {
  background: rgb(15 23 42 / 0.5);
}

Examples#

Controlled#

bind:open controls the open state with a signal. Here, Save closes the dialog from code after saving.

Closed

Rename file

The dialog closes from code after saving.

Persistent#

closeOnOutsideClick={false} keeps the dialog open when the backdrop is clicked. Escape and the buttons still close it.

Delete project?

This deletes the project and its files. You cannot undo it.

API Reference#

Root#

PropDefaultType
ids–{ trigger?: string; content?: string; title?: string; description?: string }

Overrides the element IDs of the parts.

defaultOpenfalseboolean

Whether the dialog is open initially (uncontrolled). The dialog opens when the page resumes, since showModal() runs on the client.

bind:open–Signal<boolean>

A signal with the open state (controlled).

onOpenChange$–QRL<(open: boolean) => void>

Called when the dialog opens or closes by a user interaction.

Also accepts all <div> attributes.

Data attributeValue
data-leve-dialogAlways present
data-state"open" | "closed"

The open state is uncontrolled with defaultOpen, or controlled with bind:open. onOpenChange$ is called when the user opens or closes the dialog. The SSR HTML always renders the dialog closed: a dialog that is open initially opens when the page resumes, since showModal() runs on the client.

Trigger#

PropDefaultType
as'button'keyof HTMLElementTagNameMap | Component<any>

The element or component to render instead of <button>. A component must spread the props it receives onto one element.

Also accepts all <button> attributes.

Data attributeValue
data-leve-dialog-triggerAlways present
data-state"open" | "closed"

Content#

PropDefaultType
closeOnEscapetrueboolean

Whether Escape closes the dialog. Browsers may still close it when Escape is pressed twice without any other interaction; the state follows.

closeOnOutsideClicktrueboolean

Whether a pointer down outside the dialog (on its backdrop) closes it.

Also accepts all <dialog> attributes.

Data attributeValue
data-leve-dialog-contentAlways present
data-state"open" | "closed"

The browser adds the open attribute while the dialog is shown. Use [open] with @starting-style to animate the dialog and its ::backdrop when they appear, as in the demos.

Title#

No props of its own. Accepts all <h2> attributes.

Data attributeValue
data-leve-dialog-titleAlways present

Description#

No props of its own. Accepts all <p> attributes.

Data attributeValue
data-leve-dialog-descriptionAlways present

Close#

PropDefaultType
as'button'keyof HTMLElementTagNameMap | Component<any>

The element or component to render instead of <button>. A component must spread the props it receives onto one element.

Also accepts all <button> attributes.

Data attributeValue
data-leve-dialog-closeAlways present
data-state"open" | "closed"

Accessibility#

Complies with the Dialog (Modal) WAI-ARIA design pattern.

  • Dialog.Content is a native <dialog> opened with showModal(), so the rest of the page is inert while it is open. It renders aria-modal="true", aria-labelledby pointing to Dialog.Title and aria-describedby pointing to Dialog.Description.
  • Dialog.Trigger renders aria-haspopup="dialog", aria-expanded and aria-controls pointing to the Content.
  • When the dialog opens, focus moves to its first focusable element (or to the Content if it has none), and Tab stays inside the dialog. When it closes, focus returns to the element that was focused before it opened, or to the Trigger.
  • The page behind the dialog does not scroll while it is open.
  • If Dialog.Close only contains an icon, give it an aria-label.

Keyboard Interactions#

KeyDescription
TabMoves focus to the next focusable element in the dialog. From the last one, moves to the first.
Shift + TabMoves focus to the previous focusable element in the dialog. From the first one, moves to the last.
EscapeCloses the dialog, unless closeOnEscape is false.