Dialog

Modal dialogs with focus trap and backdrop handling.

Props

Scroll Lock Close on Escape Close on Outside Click

Features

🪟 Uses native HTML <dialog> element
🔒 Built-in scroll lock when open
🎯 Focus trap and focus management
🎨 Animation support with custom overlay

Usage

Builder

<script lang="ts">
  import { Dialog } from "melt/builders";

  const dialog = new Dialog();
</script>

<button {...dialog.trigger}>
  Open Dialog
</button>

<!-- Optional overlay for animations -->
<div {...dialog.overlay}></div>

<dialog {...dialog.content}>
  Dialog content
</dialog>

Animations

Dialogs support smooth animations for both the content and backdrop. To enable animations, use the overlay element instead of the native ::backdrop pseudo-element.

Basic Animation Setup

With Animations

<script lang="ts">
  import { Dialog } from "melt/builders";

  const dialog = new Dialog();
</script>

<button {...dialog.trigger}>
  Open Dialog
</button>

<!-- Overlay with fade animation -->
<div {...dialog.overlay}></div>

<!-- Dialog with scale and fade animation -->
<dialog {...dialog.content}>
  <h2>Hello!</h2>
  <button onclick={() => dialog.open = false}>Close</button>
</dialog>

<style>
  dialog {
    width: 24rem;
    background: white;
    opacity: 0;
    scale: 0.95;
    transition: ease 300ms;
  }

  dialog::backdrop {
    display: none;
  }

  dialog[data-open] {
    opacity: 1;
    scale: 1;
  }

  [data-melt-dialog-overlay] {
    position: fixed;
    width: 100%;
    height: 100%;
    background: black;
    opacity: 0;
    transition: ease 300ms;
  }

  [data-melt-dialog-overlay][data-open] {
    opacity: 0.1;
  }
</style>

How It Works

When you set dialog.open = true:

The overlay element shows using the Popover API
The dialog element shows with showModal()
A tick() occurs to update the data-open attribute
CSS transitions animate the elements to their open state

When you set dialog.open = false:

The data-open attribute is removed immediately
CSS transitions animate elements to their closed state
When transitions complete, the dialog and overlay are closed

Animation Tips

Transition Duration: Ensure the transitionend event fires by using CSS transitions with non-zero duration
Backdrop: Hide the native backdrop with dialog::backdrop { display: none; } when using the custom overlay

API Reference

Constructor Props

The props that are passed when calling

new Dialog()

export type DialogProps = {
  /**
   * If the Dialog is open.
   *
   * When passing a getter, it will be used as source of truth,
   * meaning that the value only changes when the getter returns a new value.
   *
   * Otherwise, if passing a static value, it'll serve as the default value.
   *
   * @default false
   */
  open?: MaybeGetter<boolean | undefined>;

  /**
   * Called when the value is supposed to change.
   */
  onOpenChange?: (value: boolean) => void;

  /**
   * If the dialog should close when clicking escape.
   *
   * @default true
   */
  closeOnEscape?: MaybeGetter<boolean | undefined>;

  /**
   * If the dialog should close when clicking outside.
   * Alternatively, accepts a function that receives the clicked element,
   * and returns if the dialog should close.
   *
   * @default true
   */
  closeOnOutsideClick?: MaybeGetter<boolean | undefined>;

  /**
   * If the dialog should lock the document scroll when open.
   *
   * @default true
   */
  scrollLock?: MaybeGetter<boolean | undefined>;
};

export type DialogProps = {
  /**
   * If the Dialog is open.
   *
   * When passing a getter, it will be used as source of truth,
   * meaning that the value only changes when the getter returns a new value.
   *
   * Otherwise, if passing a static value, it'll serve as the default value.
   *
   * @default false
   */
  open?: MaybeGetter<boolean | undefined>;

  /**
   * Called when the value is supposed to change.
   */
  onOpenChange?: (value: boolean) => void;

  /**
   * If the dialog should close when clicking escape.
   *
   * @default true
   */
  closeOnEscape?: MaybeGetter<boolean | undefined>;

  /**
   * If the dialog should close when clicking outside.
   * Alternatively, accepts a function that receives the clicked element,
   * and returns if the dialog should close.
   *
   * @default true
   */
  closeOnOutsideClick?: MaybeGetter<boolean | undefined>;

  /**
   * If the dialog should lock the document scroll when open.
   *
   * @default true
   */
  scrollLock?: MaybeGetter<boolean | undefined>;
};

Properties

The properties returned from

new Dialog()

closeOnEscape
```
boolean
```
```
boolean
```
closeOnOutsideClick
```
boolean
```
```
boolean
```
scrollLock
```
boolean
```
```
boolean
```

refs

{
  get: (key: "trigger" | "content" | "overlay") => HTMLElement | undefined
  attach: (key: "trigger" | "content" | "overlay") => Attachment<HTMLElement>
  key: any
}

open
```
boolean
```
```
boolean
```

sharedProps

{ "data-open": "" | undefined }

trigger

{
  readonly "data-open": "" | undefined
  readonly "data-melt-dialog-trigger": ""
  readonly onclick: () => void
  readonly type: "button"
}

The trigger element.

content

{
  readonly "data-open": "" | undefined
  readonly "data-melt-dialog-content": ""
  readonly onclose: () => void
}

The element for the dialog itself.

overlay

{
  readonly "data-open": "" | undefined
  readonly "data-melt-dialog-overlay": ""
  readonly popover: "manual"
  readonly "aria-hidden": true
}

Optional overlay element, to replace dialog::backdrop for animation support