Dialog

Features

• Fully managed focus
• Can be controlled or uncontrolled
• Esc closes the component automatically

Anatomy

At a high level, the anatomy of a dialog looks like this:

    <script lang="ts">
  import { createDialog, melt } from '@melt-ui/svelte'
  const {
    elements: { trigger, portalled, overlay, content, title, description, close },
    states: { open }
  } = createDialog()
</script>
 
<button use:melt={$trigger}> Open Dialog </button>
 
{#if $open}
  <div use:melt={$portalled}>
    <div use:melt={$overlay} />
    <div use:melt={$content}>
      <h2 use:melt={$title}>Dialog Title</h2>
      <p use:melt={$description}>Dialog description</p>
      <button use:melt={$close}> Close Dialog </button>
    </div>
  </div>
{/if}
	

    <script lang="ts">
  import { createDialog, melt } from '@melt-ui/svelte'
  const {
    elements: { trigger, portalled, overlay, content, title, description, close },
    states: { open }
  } = createDialog()
</script>
 
<button {...$trigger} use:trigger> Open Dialog </button>
 
{#if $open}
  <div {...$portalled} use:portalled>
    <div {...$overlay} use:overlay />
    <div {...$content} use:content>
      <h2 {...$title} use:title>Dialog Title</h2>
      <p {...$description} use:description>Dialog description</p>
      <button {...$close} use:close> Close Dialog </button>
    </div>
  </div>
{/if}
	

• Trigger: The button(s) that open the dialog
• Portalled: The container that is portalled (to body, by default)
• Overlay: The dim background that is typically behind a dialog element.
• Content: Container for the content within the dialog.
  • Title: The title of the dialog
  • Description: The description which supports the title
  • Close: The button(s) that close the dialog

Usage

To create a dialog, use the createDialog builder function. You can then reference the anatomy, example above, or the Example Components below to create your dialog.

Dialog vs. Alert Dialog

You should use a dialog to display content that isn't critical to the user's workflow. For example, a user may need to select a color or a chart, but the chart will still be displayed even if the user does not select a color. In this case, a dialog would be appropriate.

On the other hand, an alert dialog should be used to display content that is critical to the user's workflow. For example, a user may need to confirm a decision before proceeding. In this case, an alert dialog would be appropriate.

By default, we set the role attribute to dialog. If you want it to be considered an alert dialog, you can set the role builder prop to alertdialog.

    const dialog = createDialog({
  role: 'alertdialog'
})
	

    const dialog = createDialog({
  role: 'alertdialog'
})
	

Disable Scroll Prevention

By default, scrolling is prevented on the body when a dialog is open. You can disable this behavior by setting the preventScroll builder prop to false.

    const dialog = createDialog({
  preventScroll: false
})
	

    const dialog = createDialog({
  preventScroll: false
})
	

Disable Close on Outside Click

By default, clicking outside of the dialog will close it. You can disable this behavior by setting the closeOnOutsideClick builder prop to false.

    const {
  /* ... */
} = createDialog({
  closeOnOutsideClick: false
})
	

    const {
  /* ... */
} = createDialog({
  closeOnOutsideClick: false
})
	

Disable Close on Escape

By default, pressing the escape key will close the dialog. You can disable this behavior by setting the escapeBehavior builder prop to ignore.

    const dialog = createDialog({
  escapeBehavior: 'ignore'
})
	

    const dialog = createDialog({
  escapeBehavior: 'ignore'
})
	

Example Components

Drawer

An overlay window can display various content, including dialogs, drawers, sidebars, and more. For example, here's a drawer component that slides in from the left side of the screen. A drawer could be used for a navigation menu, a settings panel, or any other content that you want to display in a drawer.

Alert Dialog

It's common to use a dialog as a pop-up decision window or alert dialog. For example, here's a pop-up that asks the user to confirm a decision.

Nested Dialogs

Dialogs can be nested. For example, here's a dialog that opens another dialog.

API Reference

Accessibility

Adheres to the Dialog WAI-ARIA design pattern and Alert Dialog WAI-ARIA design pattern