# <motion-dialog>

Animated modal dialog. Slides up with spring physics on open, springs back
down on close. Built on the native `<dialog>` element for top-layer stacking
and built-in accessibility. Open/close via the `open` attribute or `show()`
/ `close()` methods.

**Use it for:** confirmations, short forms and focused tasks that must
block the rest of the page until the person responds.

**Avoid it for:** hints, menus or notes that should not block the page; use
the native `popover` attribute or `<details>` for those. To enlarge images
from a grid, use `motion-gallery`, which has its own lightbox.

**Accessibility:** it opens a native `<dialog>` with `showModal()`, so the
browser moves focus into the dialog and makes the rest of the page inert.
Escape closes it with the exit animation. The component gives the dialog
no accessible name, so start the content with a clear heading, and always
include a visible close button.

**Reduced motion:** the panel and the backdrop appear and disappear at
once, with no slide or fade. `motion-close` still fires after the dialog
closes.

**Older browsers:** Safari before 17.4 and Chrome before 122 do not pass
custom properties to `::backdrop`. There the backdrop appears at once,
without a fade, and uses the default color and blur.

**Common mistakes:** listening for the native `close` event on
`motion-dialog`; it does not reach the host, so listen for `motion-close`.
Expecting a click outside the panel to close the dialog; that only happens
with `light-dismiss`.

Docs: https://www.motion-components.dev/docs/components/motion-dialog/

## Install

```js
import 'motion-components/motion-dialog'
```

Or without a build step:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/motion-components@1/dist/motion-dialog.js/+esm"></script>
```

## Example

```html
<button onclick="document.querySelector('#dlg').show()">Open</button>

<motion-dialog id="dlg">
  <h2>Hello</h2>
  <p>Spring-animated modal dialog.</p>
  <button onclick="this.closest('motion-dialog').close()">Close</button>
</motion-dialog>
```

## Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | `false` | Whether the dialog is open. Set this attribute to open declaratively. |
| `duration` | `number` | `0.5` | Spring duration for enter/exit animations, in seconds. |
| `bounce` | `number` | `0.25` | Spring bounciness (0 = critically damped, higher = more elastic). |
| `y` | `number` | `40` | Initial vertical offset for the slide-up entrance, in pixels. |
| `no-backdrop` | `boolean` | `false` | When present, the dimmed/blurred overlay is hidden. The dialog floats without a backdrop. |
| `light-dismiss` | `boolean` | `false` | When present, clicking the backdrop outside the panel closes the dialog. |

## Methods

| Method | Description |
| --- | --- |
| `show()` | Opens the dialog with the entrance animation. |
| `close()` | Closes the dialog with the exit animation. |

## Events

The `motion-*` events bubble and are composed.

| Event | Description |
| --- | --- |
| `motion-open` | Dispatched when the dialog opens, as the entrance animation starts. |
| `motion-close` | Dispatched after the close animation completes. |

## Slots

| Slot | Description |
| --- | --- |
| (default) | Content rendered inside the dialog panel. |

## CSS custom properties

| Property | Description |
| --- | --- |
| `--mc-dialog-bg` | Panel background. Default `var(--mc-color-surface, Canvas)`. |
| `--mc-dialog-color` | Panel text color. Default `var(--mc-color-text, CanvasText)`. |
| `--mc-dialog-radius` | Panel corner radius. Default `16px`. |
| `--mc-dialog-padding` | Panel padding. Default `2rem`. |
| `--mc-dialog-max-width` | Maximum panel width. Default `min(560px, 100vw - 2rem)`. |
| `--mc-dialog-max-height` | Maximum panel height. Default `100dvh - 4rem`. |
| `--mc-dialog-shadow` | Panel box shadow. The default ends with a 1px ring in `var(--mc-color-border, rgba(0, 0, 0, 0.08))`. |
| `--mc-dialog-backdrop-color` | Backdrop overlay color. Default `rgba(0, 0, 0, 0.48)`. |
| `--mc-dialog-backdrop-blur` | Backdrop `backdrop-filter`. Default `blur(6px)`. |