ReferenceDialogs

media-dialog

A modal dialog for application content, including players opened from a thumbnail

Import

import '@videojs/html/ui/dialog';
import '@videojs/html/ui/dialog-backdrop';
import '@videojs/html/ui/dialog-popup';
import '@videojs/html/ui/dialog-title';
import '@videojs/html/ui/dialog-description';
import '@videojs/html/ui/dialog-close';

Anatomy

<button commandfor="video-dialog">Open video</button>
<media-dialog id="video-dialog">
  <media-dialog-backdrop></media-dialog-backdrop>
  <media-dialog-popup>
    <media-dialog-title></media-dialog-title>
    <media-dialog-description></media-dialog-description>
    <media-dialog-close></media-dialog-close>
  </media-dialog-popup>
</media-dialog>

Behavior

<media-dialog> provides the modal interaction and accessibility behavior while your application supplies the content and styling. It is the general-purpose replacement for a ModalDialog use case such as opening a player from a thumbnail.

Place a button immediately before media-dialog, or connect them explicitly with commandfor and an id. You can also set the dialog’s open property directly. The root provides state without creating a layout box; media-dialog-backdrop and media-dialog-popup are sibling surfaces. The element dispatches open-change when its state changes and open-change-complete after the popup transition finishes.

The close part and Escape close the dialog. Other buttons inside the dialog, including player controls, do not close it.

Inside and outside a player

A dialog inside a player is confined to that player. The rest of the player becomes inert, but the page around it stays interactive and aria-modal is omitted. A dialog outside a player is modal for the whole page, with aria-modal="true" and everything outside the popup inert.

The backdrop and popup get data-scope: player inside a player and document outside one. The built-in skin styles use it to switch from position: absolute to position: fixed. In your own styles, give a dialog outside a player position: fixed so it covers the viewport, as with any headless dialog. Inside a skin, give the backdrop and popup a z-index above the controls; the built-in skins use 40 and 50.

Your application decides what opening and closing mean for the media. The example starts playback after opening and pauses it as soon as the dialog closes. Handle the promise returned by play(), since browsers can reject autoplay when it is not allowed.

Use <media-alert-dialog> for urgent messages that require acknowledgement. <media-error-dialog> is the player-error specialization. Both use the same dialog behavior.

Styling

Use the open and transition data attributes to style the modal and its animations:

Attribute	Description
`data-open`	Present while the dialog is open, including its closing transition
`data-starting-style`	Present at the start of the opening transition
`data-ending-style`	Present during the closing transition
`data-scope`	`player` inside a player, `document` outside one

media-dialog-backdrop {
  position: absolute;
  z-index: 40;
}

media-dialog-popup {
  position: absolute;
  z-index: 50;
}

media-dialog-backdrop[data-scope="document"],
media-dialog-popup[data-scope="document"] {
  position: fixed;
}

media-dialog-backdrop:not([data-open]),
media-dialog-popup:not([data-open]) {
  display: none;
}

media-dialog-backdrop[data-starting-style],
media-dialog-backdrop[data-ending-style],
media-dialog-popup[data-starting-style],
media-dialog-popup[data-ending-style] {
  opacity: 0;
}

Accessibility

The popup uses role="dialog", plus aria-modal="true" outside a player. Include <media-dialog-title> so the dialog always has an accessible name. <media-dialog-description> is optional. These parts receive generated IDs connected through aria-labelledby and aria-describedby. The trigger receives aria-haspopup, aria-controls, and aria-expanded.

When the dialog opens, focus moves to an element with autofocus, the first focusable element, or the popup itself. Tab and Shift + Tab keep focus within the dialog, and content outside the dialog, within its player or the page, becomes inert. Closing restores focus to the trigger, or to the element that was focused before the dialog opened.

Dialogs inside the same player container share modal coordination. Opening one closes the current dialog and dismisses any open menu, tooltip, or popover before focus moves into the new popup.

Examples

Open the video from its thumbnail. Playback starts when the dialog opens and pauses when it closes.

Video title

A video opened from a thumbnail.

<div class="html-dialog-basic">
  <button class="html-dialog-basic__trigger" type="button" commandfor="html-video-dialog">
    <img src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg" alt="" />
    <span>Play the video</span>
  </button>
  <media-dialog id="html-video-dialog">
    <media-dialog-backdrop class="html-dialog-basic__backdrop"></media-dialog-backdrop>
    <media-dialog-popup class="html-dialog-basic__dialog">
      <div class="html-dialog-basic__popup">
        <media-dialog-title class="html-dialog-basic__title">Video title</media-dialog-title>
        <media-dialog-description class="html-dialog-basic__description">
          A video opened from a thumbnail.
        </media-dialog-description>
        <media-dialog-close class="html-dialog-basic__close">Close</media-dialog-close>
        <video-player>
          <media-container>
            <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" controls muted playsinline></video>
          </media-container>
        </video-player>
      </div>
    </media-dialog-popup>
  </media-dialog>
</div>

.html-dialog-basic {
  position: relative;
  min-height: 320px;
}

.html-dialog-basic__trigger {
  display: grid;
  gap: 10px;
  width: min(100%, 420px);
  padding: 0 0 12px;
  overflow: hidden;
  color: white;
  cursor: pointer;
  background: #111827;
  border: 0;
  border-radius: 12px;
}

.html-dialog-basic__trigger img {
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
  object-fit: cover;
}

.html-dialog-basic__backdrop {
  position: absolute;
  inset: 0;
  z-index: 1;
  background: rgb(3 7 18 / 80%);
  transition: opacity 200ms ease;
}

.html-dialog-basic__dialog {
  position: absolute;
  inset: 0;
  z-index: 2;
  display: flex;
  align-items: center;
  justify-content: center;
  padding: 20px;
  transition: opacity 150ms ease;
}

.html-dialog-basic__backdrop:not([data-open]),
.html-dialog-basic__dialog:not([data-open]) {
  display: none;
}

.html-dialog-basic__backdrop[data-starting-style],
.html-dialog-basic__backdrop[data-ending-style],
.html-dialog-basic__dialog[data-starting-style],
.html-dialog-basic__dialog[data-ending-style] {
  opacity: 0;
}

.html-dialog-basic__popup {
  position: relative;
  width: 100%;
  max-width: 560px;
  padding: 16px;
  color: white;
  background: #111827;
  border-radius: 12px;
}

.html-dialog-basic__title {
  display: block;
  margin-bottom: 4px;
  font-size: 1.125rem;
  font-weight: 600;
}

.html-dialog-basic__description {
  display: block;
  margin-bottom: 12px;
}

.html-dialog-basic__close {
  position: absolute;
  top: 12px;
  right: 12px;
  padding: 6px 12px;
  color: #111827;
  cursor: pointer;
  background: white;
  border: 0;
  border-radius: 9999px;
}

.html-dialog-basic video {
  display: block;
  width: 100%;
}

@media (prefers-reduced-motion: reduce) {
  .html-dialog-basic__backdrop,
  .html-dialog-basic__dialog {
    transition: none;
  }
}

import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/dialog';
import '@videojs/html/ui/dialog-backdrop';
import '@videojs/html/ui/dialog-popup';
import '@videojs/html/ui/dialog-title';
import '@videojs/html/ui/dialog-description';
import '@videojs/html/ui/dialog-close';

const initializedDemos = new WeakSet<HTMLElement>();

function initializeDemos(): void {
  document.querySelectorAll<HTMLElement>('.html-dialog-basic').forEach((demo) => {
    if (initializedDemos.has(demo)) return;

    initializedDemos.add(demo);

    const dialog = demo.querySelector('media-dialog');
    const video = demo.querySelector('video');

    dialog?.addEventListener('open-change', (event) => {
      if (!video) return;

      // SAFETY: `media-dialog` defines `open-change` with an `{ open }` detail payload.
      const { open } = (event as CustomEvent<{ open: boolean }>).detail;

      if (open) void video.play().catch(() => {});
      else video.pause();
    });
  });
}

initializeDemos();
document.addEventListener('astro:page-load', initializeDemos);

API Reference

media-dialog

Manages dialog state and provides it to the compound parts.

Props

Prop	Type	Default
`closeOnEscape` attribute `close-on-escape`	`boolean`	`true`
Description Whether pressing Escape closes the dialog.
`defaultOpen` attribute `default-open`	`boolean`	`false`
Description Initial open state for uncontrolled usage.
`open`	`boolean`	`false`
Description Controlled open state. When set, the consumer is responsible for toggling.

State

State is reflected as data attributes for CSS styling.

Property	Type	Details
`transitionStarting`	`boolean`
Description Whether the open transition is in progress.
`transitionEnding`	`boolean`
Description Whether the close transition is in progress.
`open`	`boolean`
Description Whether the dialog is currently open.
`status`	`'idle' \| 'starting' \| 'ending'`
Description Current phase of the transition lifecycle.
`titleId`	`string \| undefined`
Description Element ID of the dialog title, used for `aria-labelledby`.
`descriptionId`	`string \| undefined`
Description Element ID of the dialog description, used for `aria-describedby`.
`scope`	`'player' \| 'document'`
Description `player` when the dialog is rendered inside a player and confined to it, otherwise `document`.

Data attributes

Attribute	Type	Details
`data-open`	—
Description Present when the dialog is open.
`data-starting-style`	—
Description Present during the open transition.
`data-ending-style`	—
Description Present during the close transition.
`data-scope`	`'player' \| 'document'`
Description `player` when the dialog is confined to its player, otherwise `document`.

Events

Event	Description
`open-change`
`open-change-complete`

media-dialog-backdrop

Presentational backdrop that reflects its owning dialog's state.

Data attributes

Attribute	Type	Details
`data-open`	—
Description Present when the dialog is open.
`data-starting-style`	—
Description Present during the open transition.
`data-ending-style`	—
Description Present during the close transition.
`data-scope`	`'player' \| 'document'`
Description `player` when the dialog is confined to its player, otherwise `document`.

media-dialog-close

Button that closes its owning dialog; the element itself takes role="button" and keyboard focus.

Data attributes

Attribute	Type	Details
`data-open`	—
Description Present when the dialog is open.
`data-starting-style`	—
Description Present during the open transition.
`data-ending-style`	—
Description Present during the close transition.
`data-scope`	`'player' \| 'document'`
Description `player` when the dialog is confined to its player, otherwise `document`.

media-dialog-description

Text announced as its owning dialog's description. The element takes the id that the popup's aria-describedby points to.

Semantic popup that owns focus management and dialog transition completion.

Attribute	Type	Details
`data-open`	—
Description Present when the dialog is open.
`data-starting-style`	—
Description Present during the open transition.
`data-ending-style`	—
Description Present during the close transition.
`data-scope`	`'player' \| 'document'`
Description `player` when the dialog is confined to its player, otherwise `document`.

media-dialog-title

Text that labels its owning dialog. The element takes the id that the popup's aria-labelledby points to.

Import

Anatomy

Behavior

Inside and outside a player

Styling

Accessibility

Examples

Player modal

API Reference

media-dialog

Props

State

Data attributes

Events

media-dialog-backdrop

Data attributes

media-dialog-close

Data attributes

media-dialog-description

media-dialog-popup

Data attributes

media-dialog-title