Dialog
A modal window that asks the user for input or a decision.
Dialog follows the Dialog (Modal) WAI-ARIA design pattern.
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>
);
});.dialog-default-trigger,
.dialog-default-button {
padding: 8px 14px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
font: inherit;
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.dialog-default-trigger:hover,
.dialog-default-button:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.dialog-default-button-primary {
border-color: #009dfd;
background: #009dfd;
color: #ffffff;
}
.dialog-default-button-primary:hover {
background: #006ce9;
}
/* The Content is a native <dialog>; margin: auto centers it, also after a CSS reset */
.dialog-default-content {
position: relative;
margin: auto;
width: min(400px, calc(100vw - 32px));
padding: 24px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
font-family: inherit;
box-shadow: 0 16px 40px rgb(15 23 42 / 0.25);
}
/* The backdrop is the ::backdrop of the <dialog> */
.dialog-default-content::backdrop {
background: light-dark(rgb(15 23 42 / 0.5), rgb(0 0 0 / 0.6));
}
/* Fade in when the dialog opens */
.dialog-default-content[open],
.dialog-default-content[open]::backdrop {
transition: opacity 150ms ease;
@starting-style {
opacity: 0;
}
}
.dialog-default-title {
margin: 0;
font-size: 18px;
font-weight: 600;
}
.dialog-default-description {
margin: 6px 0 20px;
font-size: 14px;
color: light-dark(#475569, #c9ddf0);
}
.dialog-default-label {
display: flex;
flex-direction: column;
gap: 6px;
font-size: 14px;
font-weight: 500;
}
.dialog-default-input {
padding: 8px 10px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
font: inherit;
color: inherit;
}
.dialog-default-actions {
display: flex;
justify-content: flex-end;
gap: 8px;
margin-top: 24px;
}
.dialog-default-close {
position: absolute;
top: 12px;
right: 12px;
display: inline-flex;
padding: 4px;
border: none;
border-radius: 6px;
background: none;
color: light-dark(#475569, #c9ddf0);
cursor: pointer;
}
.dialog-default-close:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.dialog-default-icon {
width: 16px;
height: 16px;
}
.dialog-default-trigger:focus-visible,
.dialog-default-button:focus-visible,
.dialog-default-close:focus-visible,
.dialog-default-input:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}Installation#
Install the individual package, or use @leve-ui/core to get every component at once:
pnpm add @leve-ui/dialognpm install @leve-ui/dialogyarn add @leve-ui/dialogbun add @leve-ui/dialogpnpm add @leve-ui/corenpm install @leve-ui/coreyarn add @leve-ui/corebun add @leve-ui/coreAnatomy#
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>
| Part | Element | Description |
|---|---|---|
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.
import { $, component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Dialog } from '@leve-ui/dialog';
import styles from './controlled.css?inline';
export default component$(() => {
useStyles$(styles);
const open = useSignal(false);
const saved = useSignal(false);
const save$ = $(() => {
saved.value = true;
open.value = false;
});
return (
<Dialog.Root bind:open={open} class="dialog-controlled">
<Dialog.Trigger class="dialog-controlled-trigger">Rename</Dialog.Trigger>
<span class="dialog-controlled-status">
{open.value ? 'Open' : saved.value ? 'Saved' : 'Closed'}
</span>
<Dialog.Content class="dialog-controlled-content">
<Dialog.Title class="dialog-controlled-title">Rename file</Dialog.Title>
<Dialog.Description class="dialog-controlled-description">
The dialog closes from code after saving.
</Dialog.Description>
<label class="dialog-controlled-label">
File name
<input class="dialog-controlled-input" name="file" value="report.pdf" />
</label>
<div class="dialog-controlled-actions">
<Dialog.Close class="dialog-controlled-button">Cancel</Dialog.Close>
<button
type="button"
class="dialog-controlled-button dialog-controlled-button-primary"
onClick$={save$}
>
Save
</button>
</div>
</Dialog.Content>
</Dialog.Root>
);
});.dialog-controlled-trigger,
.dialog-controlled-button {
padding: 8px 14px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
font: inherit;
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.dialog-controlled-trigger:hover,
.dialog-controlled-button:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.dialog-controlled-button-primary {
border-color: #009dfd;
background: #009dfd;
color: #ffffff;
}
.dialog-controlled-button-primary:hover {
background: #006ce9;
}
/* The Content is a native <dialog>; margin: auto centers it, also after a CSS reset */
.dialog-controlled-content {
position: relative;
margin: auto;
width: min(400px, calc(100vw - 32px));
padding: 24px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
font-family: inherit;
box-shadow: 0 16px 40px rgb(15 23 42 / 0.25);
}
/* The backdrop is the ::backdrop of the <dialog> */
.dialog-controlled-content::backdrop {
background: light-dark(rgb(15 23 42 / 0.5), rgb(0 0 0 / 0.6));
}
/* Fade in when the dialog opens */
.dialog-controlled-content[open],
.dialog-controlled-content[open]::backdrop {
transition: opacity 150ms ease;
@starting-style {
opacity: 0;
}
}
.dialog-controlled-title {
margin: 0;
font-size: 18px;
font-weight: 600;
}
.dialog-controlled-description {
margin: 6px 0 20px;
font-size: 14px;
color: light-dark(#475569, #c9ddf0);
}
.dialog-controlled-label {
display: flex;
flex-direction: column;
gap: 6px;
font-size: 14px;
font-weight: 500;
}
.dialog-controlled-input {
padding: 8px 10px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
font: inherit;
color: inherit;
}
.dialog-controlled-actions {
display: flex;
justify-content: flex-end;
gap: 8px;
margin-top: 24px;
}
.dialog-controlled-close {
position: absolute;
top: 12px;
right: 12px;
display: inline-flex;
padding: 4px;
border: none;
border-radius: 6px;
background: none;
color: light-dark(#475569, #c9ddf0);
cursor: pointer;
}
.dialog-controlled-close:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.dialog-controlled-icon {
width: 16px;
height: 16px;
}
.dialog-controlled-trigger:focus-visible,
.dialog-controlled-button:focus-visible,
.dialog-controlled-close:focus-visible,
.dialog-controlled-input:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.dialog-controlled {
display: flex;
align-items: center;
gap: 12px;
font-family: inherit;
}
.dialog-controlled-status {
font-size: 14px;
color: light-dark(#475569, #c9ddf0);
}Persistent#
closeOnOutsideClick={false} keeps the dialog open when the backdrop is clicked. Escape and the buttons still close it.
import { component$, type PropsOf, Slot, useStyles$ } from '@builder.io/qwik';
import { Dialog } from '@leve-ui/dialog';
import styles from './persistent.css?inline';
// Custom button component passed via `as` must spread received props onto one element
const Button = component$<PropsOf<'button'>>(({ type = 'button', ...props }) => (
<button type={type} {...props}>
<Slot />
</button>
));
export default component$(() => {
useStyles$(styles);
return (
<Dialog.Root class="dialog-persistent">
<Dialog.Trigger as={Button} class="dialog-persistent-trigger">
Delete project
</Dialog.Trigger>
{/* Clicking the backdrop does not close it; Escape and the buttons still do */}
<Dialog.Content closeOnOutsideClick={false} class="dialog-persistent-content">
<Dialog.Title class="dialog-persistent-title">Delete project?</Dialog.Title>
<Dialog.Description class="dialog-persistent-description">
This deletes the project and its files. You cannot undo it.
</Dialog.Description>
<div class="dialog-persistent-actions">
<Dialog.Close as={Button} class="dialog-persistent-button">
Cancel
</Dialog.Close>
<Dialog.Close
as={Button}
class="dialog-persistent-button dialog-persistent-button-primary"
>
Delete
</Dialog.Close>
</div>
</Dialog.Content>
</Dialog.Root>
);
});.dialog-persistent-trigger,
.dialog-persistent-button {
padding: 8px 14px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
font: inherit;
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.dialog-persistent-trigger:hover,
.dialog-persistent-button:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.dialog-persistent-button-primary {
border-color: #009dfd;
background: #009dfd;
color: #ffffff;
}
.dialog-persistent-button-primary:hover {
background: #006ce9;
}
/* The Content is a native <dialog>; margin: auto centers it, also after a CSS reset */
.dialog-persistent-content {
position: relative;
margin: auto;
width: min(400px, calc(100vw - 32px));
padding: 24px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
font-family: inherit;
box-shadow: 0 16px 40px rgb(15 23 42 / 0.25);
}
/* The backdrop is the ::backdrop of the <dialog> */
.dialog-persistent-content::backdrop {
background: light-dark(rgb(15 23 42 / 0.5), rgb(0 0 0 / 0.6));
}
/* Fade in when the dialog opens */
.dialog-persistent-content[open],
.dialog-persistent-content[open]::backdrop {
transition: opacity 150ms ease;
@starting-style {
opacity: 0;
}
}
.dialog-persistent-title {
margin: 0;
font-size: 18px;
font-weight: 600;
}
.dialog-persistent-description {
margin: 6px 0 20px;
font-size: 14px;
color: light-dark(#475569, #c9ddf0);
}
.dialog-persistent-label {
display: flex;
flex-direction: column;
gap: 6px;
font-size: 14px;
font-weight: 500;
}
.dialog-persistent-input {
padding: 8px 10px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
font: inherit;
color: inherit;
}
.dialog-persistent-actions {
display: flex;
justify-content: flex-end;
gap: 8px;
margin-top: 24px;
}
.dialog-persistent-close {
position: absolute;
top: 12px;
right: 12px;
display: inline-flex;
padding: 4px;
border: none;
border-radius: 6px;
background: none;
color: light-dark(#475569, #c9ddf0);
cursor: pointer;
}
.dialog-persistent-close:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.dialog-persistent-icon {
width: 16px;
height: 16px;
}
.dialog-persistent-trigger:focus-visible,
.dialog-persistent-button:focus-visible,
.dialog-persistent-close:focus-visible,
.dialog-persistent-input:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}API Reference#
Root#
| Prop | Default | Type |
|---|---|---|
| ids | – | { trigger?: string; content?: string; title?: string; description?: string } Overrides the element IDs of the parts. |
| defaultOpen | false | boolean Whether the dialog is open initially (uncontrolled). The dialog opens when the page resumes, since |
| 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 attribute | Value |
|---|---|
data-leve-dialog | Always 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#
| Prop | Default | Type |
|---|---|---|
| as | 'button' | keyof HTMLElementTagNameMap | Component<any> The element or component to render instead of |
Also accepts all <button> attributes.
| Data attribute | Value |
|---|---|
data-leve-dialog-trigger | Always present |
data-state | "open" | "closed" |
Content#
| Prop | Default | Type |
|---|---|---|
| closeOnEscape | true | boolean Whether Escape closes the dialog. Browsers may still close it when Escape is pressed twice without any other interaction; the state follows. |
| closeOnOutsideClick | true | boolean Whether a pointer down outside the dialog (on its backdrop) closes it. |
Also accepts all <dialog> attributes.
| Data attribute | Value |
|---|---|
data-leve-dialog-content | Always 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 attribute | Value |
|---|---|
data-leve-dialog-title | Always present |
Description#
No props of its own. Accepts all <p> attributes.
| Data attribute | Value |
|---|---|
data-leve-dialog-description | Always present |
Close#
| Prop | Default | Type |
|---|---|---|
| as | 'button' | keyof HTMLElementTagNameMap | Component<any> The element or component to render instead of |
Also accepts all <button> attributes.
| Data attribute | Value |
|---|---|
data-leve-dialog-close | Always present |
data-state | "open" | "closed" |
Accessibility#
Complies with the Dialog (Modal) WAI-ARIA design pattern.
Dialog.Contentis a native<dialog>opened withshowModal(), so the rest of the page is inert while it is open. It rendersaria-modal="true",aria-labelledbypointing toDialog.Titleandaria-describedbypointing toDialog.Description.Dialog.Triggerrendersaria-haspopup="dialog",aria-expandedandaria-controlspointing 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.Closeonly contains an icon, give it anaria-label.
Keyboard Interactions#
| Key | Description |
|---|---|
Tab | Moves focus to the next focusable element in the dialog. From the last one, moves to the first. |
Shift + Tab | Moves focus to the previous focusable element in the dialog. From the first one, moves to the last. |
Escape | Closes the dialog, unless closeOnEscape is false. |