--- url: /reference/items/Dialog/js-api.md --- # JS API ## Options ### `modal` * Type: `Boolean` * Default: `true` Open the dialog as a true modal with [`showModal()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal): the platform then handles the focus trap, makes the rest of the page [`inert`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/inert), restores focus on close and paints the dialog in the top layer. Set it to `false` (via `data-option-no-modal`) to use [`show()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/show) instead, which keeps the rest of the page interactive (useful for a slide-in nav). ```html {2} ... ``` ### `trapFocus` * Type: `Boolean` * Default: `true` Trap the tabulation inside the dialog. This is **only meaningful on the non-modal path** (`modal: false`): `showModal()` already traps focus natively, so the option is a no-op when `modal` is `true`. On the non-modal path it saves the active element on open, keeps Tab inside the dialog while open, and restores focus on close. ```html {3} ... ``` ### `scrollLock` * Type: `Boolean` * Default: `true` Lock the scroll on the document element while the dialog is open by toggling `document.documentElement.style.overflow`. Set it to `false` with `data-option-no-scroll-lock` to leave the page scrollable. ## Properties ### `dialog` * Type: `HTMLDialogElement` A getter returning the native `` element (`this.$el`). ### `transitions` * Type: `Array` A getter returning every [`Transition`](/reference/items/Transition/) and [`ViewTransition`](/reference/items/ViewTransition/) child the dialog orchestrates. ## Methods ### `open` * Returns `Promise` Open the dialog: call `showModal()` (or `show()` when `modal` is `false`), lock the scroll, emit `open`, then run every child's `enter()` alongside the [`waitUntil` extensions](#extending-the-choreography-with-waituntil). A no-op if the dialog is already open. Resolves once the enter choreography has finished. ### `close` * Returns `Promise` Close the dialog: emit `close`, run every child's `leave()` alongside the [`waitUntil` extensions](#extending-the-choreography-with-waituntil), **then** call `dialog.close()`, release the focus-trap (non-modal path) and unlock the scroll. A no-op if the dialog is already closed, and concurrent calls await the same run. Resolves once closed. ### `toggle` * Returns `Promise` Call `close()` if the dialog is open, `open()` otherwise. ## Events Both lifecycle events bubble up the DOM tree, so ancestors can route them and any listener up the tree can join the choreography. ### `open` Emitted when the dialog starts opening, before the enter transitions run. The `detail` carries a [`waitUntil`](#extending-the-choreography-with-waituntil) function. ### `close` Emitted when the dialog starts closing, before the leave transitions run. The `detail` carries a [`waitUntil`](#extending-the-choreography-with-waituntil) function. ## Extending the choreography with `waitUntil` Both lifecycle events expose `event.detail.waitUntil(x)`, modeled on the Service Worker [`ExtendableEvent`](https://developer.mozilla.org/en-US/docs/Web/API/ExtendableEvent/waitUntil). Any listener can register an extension while the event dispatches, and the dialog awaits it alongside its transition children — on `close`, the native dialog stays painted until every registered extension settles. This lets any component participate in the open and close choreography without being a declared child. `waitUntil()` accepts either form: * a **promise** (any thenable), awaited as is * a **transitioner**: a duck-typed object with `enter()` and `leave()` methods, e.g. [`MotionView`](/reference/items/MotionView/) from `@studiometa/ui-motion` — the dialog follows its lifecycle by awaiting `enter()` on `open` and `leave()` on `close` For example, a [`Motion`](/reference/items/Motion/) box can spring in and out with the dialog through two [`Action`](/reference/items/Action/) attributes: ```html {3,4} … ``` With the transitioner form, a single handler is enough — pass the transitioner itself and the dialog picks the right phase, like a `MotionView` navigation panel animating out before the dialog hides: ```html {3} ``` Registration is only valid synchronously, while the event dispatches; later calls warn and are ignored. A rejected extension never blocks the choreography: the rejection is reported with a warning and the run completes.