Dialog

A window overlaid on either the primary window or another dialog window, rendering the content underneath inert.

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>
 
<div use:melt={$portalled}>
  {#if $open}
    <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>
  {/if}
</div>
	
    <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>
 
<div {...$portalled} use:portalled>
  {#if $open}
    <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>
  {/if}
</div>
	
  • 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 closeOnEscape builder prop to false.

    const dialog = createDialog({
  closeOnEscape: false
})
	
    const dialog = createDialog({
  closeOnEscape: false
})
	

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

createDialog

The builder function used to create the dialog component.

Props

Prop Default Type / Description
role 'dialog'
'dialog' | 'alertdialog'

The role attribute of the dialog element.

preventScroll true
boolean

Whether or not to prevent scrolling of the document when the dialog is open.

closeOnEscape true
boolean

Whether or not to close the dialog when the escape key is pressed.

closeOnOutsideClick true
boolean

Whether or not to close the dialog when the user clicks outside of it.

portal body
string | HTMLElement | null

The element or selector to render the dialog into. Nested floating elements are automatically rendered into their parent if not specified. Pass in null to disable portalling.

forceVisible false
boolean

Whether or not to force the dialog to always be visible. This is useful for custom transitions and animations using conditional blocks.

openFocus -

Override the default focus behavior on open

closeFocus -

Override the default focus behavior on close

defaultOpen false
boolean

Whether the dialog is open by default or not.

open -
Writable<boolean>

A writable store that controls whether or not the dialog is open.

See Bring Your Own Store

onOpenChange -
ChangeFn<boolean>

A callback called when the value of the open store should be changed.

See Change Functions

ids -
Record<'content' | 'title' | 'description', string>

Override the internally generated ids for the elements.

Elements

Element Description

The builder store used to create the dialog trigger.

The builder store used to create the portalled dialog container.

The builder store used to create the dialog overlay.

The builder store used to create the dialog content.

The builder store used to create the dialog close button.

The builder store used to create the dialog title.

The builder store used to create the dialog description.

States

State Description
open

A writable store with the open state of the dialog.

Options

Option Description
role

The role attribute of the dialog element.

preventScroll

Whether or not to prevent scrolling of the document when the dialog is open.

closeOnEscape

Whether or not to close the dialog when the escape key is pressed.

closeOnOutsideClick

Whether or not to close the dialog when the user clicks outside of it.

portal

The element or selector to render the dialog into. Nested floating elements are automatically rendered into their parent if not specified. Pass in null to disable portalling.

forceVisible

Whether or not to force the dialog to always be visible. This is useful for custom transitions and animations using conditional blocks.

openFocus

Override the default focus behavior on open

closeFocus

Override the default focus behavior on close

IDs

Option Description
content

The writable store that represents the id of the content element.

title

The writable store that represents the id of the title element.

description

The writable store that represents the id of the description element.

trigger

The element which triggers the dialog to open when clicked or pressed.

Data Attributes

Data Attribute Value
[data-melt-dialog-trigger]

Present on all trigger elements.

Custom Events

Event Value
m-click (e: ) => void
m-keydown (e: ) => void

portalled

The element that will be portalled (or moved) to a different location in the DOM based on the portal prop value.

Data Attributes

Data Attribute Value
[data-portal]

Present on all portalled elements.

[data-melt-dialog-portalled]

Present on all portalled elements.

overlay

The overlay element which covers the page when the dialog is open.

Data Attributes

Data Attribute Value
[data-state]

'open' | 'closed'

[data-melt-dialog-overlay]

Present on all overlay elements.

content

The element displayed within the dialog when it is open.

Data Attributes

Data Attribute Value
[data-state]

'open' | 'closed'

[data-melt-dialog-content]

Present on all content elements.

close

The element which closes the dialog when clicked or pressed.

Data Attributes

Data Attribute Value
[data-melt-dialog-close]

Present on all close elements.

Custom Events

Event Value
m-click (e: ) => void
m-keydown (e: ) => void

title

The title of the dialog. Used for accessibility purposes.

Data Attributes

Data Attribute Value
[data-melt-dialog-title]

Present on all title elements.

description

The description of the dialog. Used for accessibility purposes.

Data Attributes

Data Attribute Value
[data-melt-dialog-description]

Present on all description elements.

Accessibility

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

Key Behavior
Space

Opens/closes the dialog.

Enter

Opens/closes the dialog.

Tab

Moves focus to the next focusable element within the dialog.

Shift + Tab

Moves focus to the previous focusable element within the dialog.

Esc

Closes the dialog and moves focus to the trigger element.