ReferenceDialogs

media-error-dialog

An alert dialog that presents and dismisses playback errors

Import

import '@videojs/html/ui/error-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

<media-error-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-error-dialog>

Behavior

<media-error-dialog> is a specialized root driven by the player’s error feature. It uses alert semantics and reuses the backdrop, popup, title, description, and close parts from <media-dialog>; it is not nested inside <media-alert-dialog>. It opens when the attached media reports an error and stays hidden otherwise. Closing it dismisses the current error in the player store.

The title, description, and close label use localized default text. Provide children to any of those parts to replace its default content. Known media error codes use the matching translated message, while custom error messages are shown as written.

The included player skins already render an error dialog. Compose this component directly when building a custom skin.

Styling

Use data-open, data-starting-style, and data-ending-style to style visibility and transitions.

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="alertdialog". Its title and description are connected with aria-labelledby and aria-describedby.

Modality is scoped to the player container rather than the page. While the error is open, the rest of the container is inert and focus that lands elsewhere inside it returns to the popup, but content outside the player stays interactive and aria-modal is omitted. Only when the popup renders outside the container does the dialog fall back to document-wide modality: aria-modal="true", Tab cycling within the popup, and everything outside it inert.

Pressing Escape or activating the close part dismisses the error.

Examples

The example replaces the video source with invalid local data so the media element reports an error without making a failing network request.

Basic usage

<video-player class="html-error-dialog-basic">
  <media-container class="html-error-dialog-basic__container">
    <video
      class="html-error-dialog-basic__video"
      src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
      autoplay
      muted
      playsinline
      loop
    ></video>
    <button class="html-error-dialog-basic__trigger" type="button">Trigger a playback error</button>
    <media-error-dialog>
      <media-dialog-backdrop class="html-error-dialog-basic__backdrop"></media-dialog-backdrop>
      <media-dialog-popup class="html-error-dialog-basic__dialog">
        <media-dialog-title class="html-error-dialog-basic__title"></media-dialog-title>
        <media-dialog-description class="html-error-dialog-basic__description"></media-dialog-description>
        <media-dialog-close class="html-error-dialog-basic__close"></media-dialog-close>
      </media-dialog-popup>
    </media-error-dialog>
  </media-container>
</video-player>

.html-error-dialog-basic__container {
  position: relative;
  display: block;
  overflow: hidden;
  border-radius: 12px;
}

.html-error-dialog-basic__video {
  display: block;
  width: 100%;
}

.html-error-dialog-basic__trigger,
.html-error-dialog-basic__close {
  padding: 8px 16px;
  color: #111827;
  cursor: pointer;
  background: #fff;
  border: 0;
  border-radius: 9999px;
}

.html-error-dialog-basic__trigger {
  position: absolute;
  bottom: 16px;
  left: 16px;
}

.html-error-dialog-basic__backdrop {
  position: absolute;
  inset: 0;
  background: rgb(3 7 18 / 92%);
  transition: opacity 150ms ease;
}

.html-error-dialog-basic__dialog {
  position: absolute;
  inset: 0;
  z-index: 1;
  display: grid;
  gap: 12px;
  place-content: center;
  padding: 32px;
  color: #fff;
  text-align: center;
  transition: opacity 150ms ease;
}

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

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

.html-error-dialog-basic__title,
.html-error-dialog-basic__description {
  display: block;
}

.html-error-dialog-basic__title {
  font-size: 20px;
  font-weight: 600;
}

.html-error-dialog-basic__description {
  color: #d1d5db;
}

.html-error-dialog-basic__close {
  justify-self: center;
}

import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/error-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 brokenSource = 'data:video/mp4;base64,AAAA';
const initializedDemos = new WeakSet<HTMLElement>();

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

    initializedDemos.add(demo);

    const video = demo.querySelector('video');
    const trigger = demo.querySelector<HTMLButtonElement>('.html-error-dialog-basic__trigger');

    trigger?.addEventListener('click', () => {
      if (!video) return;

      video.src = brokenSource;
      video.load();
    });
  });
}

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

API Reference

media-error-dialog

Opens from player error state and provides it to the shared dialog parts.

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`.

media-dialog-backdrop

Presentational backdrop that reflects its owning dialog's state.

Data attributes

Attribute	Description
`data-open`	Present when the dialog is open.
`data-starting-style`	Present during the open transition.
`data-ending-style`	Present during the close transition.

Semantic popup that owns focus management and dialog transition completion.

Attribute	Description
`data-open`	Present when the dialog is open.
`data-starting-style`	Present during the open transition.
`data-ending-style`	Present during the close transition.