ReferenceDisplay

media-status-indicator

Display temporary visual feedback for keyboard and gesture actions

Import

import '@videojs/html/ui/status-indicator';
import '@videojs/html/ui/status-indicator-value';

Anatomy

<media-status-indicator>
  <media-status-indicator-value></media-status-indicator-value>
</media-status-indicator>

Behavior

<media-status-indicator> displays feedback for actions emitted by a <media-hotkey> or <media-gesture> in the same player <media-container>. It does not react to buttons, direct player-store changes, or media state changes on their own.

The input event arrives before its action is resolved. The indicator uses the media snapshot from that moment to predict the next visual status:

Action	`data-status`	Value
`togglePaused`	`"play"` or `"pause"`	Translated playing or paused label
`toggleMuted`	`"volume-off"`, `"volume-low"`, or `"volume-high"`	Predicted volume percentage
`volumeStep`	`"volume-off"`, `"volume-low"`, or `"volume-high"`	Predicted volume percentage
`toggleSubtitles`	`"captions-on"` or `"captions-off"`	Translated captions label
`toggleFullscreen`	`"fullscreen"` or `"exit-fullscreen"`	Translated fullscreen label
`togglePictureInPicture`	`"pip"` or `"exit-pip"`	Translated picture-in-picture label

toggleSubtitles is ignored when the player reports that no captions or subtitles are available. Seek actions, toggleControls, playback-rate actions, and custom actions do not open this indicator unless you derive a custom status.

Use actions to allow only some of the supported actions. Omitting it allows all supported actions.

Set the actions attribute to action names separated by commas, whitespace, or both:

<media-status-indicator actions="togglePaused, toggleMuted">
  <media-status-indicator-value></media-status-indicator-value>
</media-status-indicator>

The indicator closes after closeDelay, which defaults to 800 milliseconds. A repeated handled action updates the current value and restarts that close timer without replaying the entry transition.

The element remains in the document with hidden until the next handled action.

Custom actions

Use deriveCustomStatus to give custom hotkey or gesture actions the same feedback as built-in actions. The indicator calls it only when an allowed action has no built-in status. It receives the input event and the pre-action media snapshot. Return { status, label, value } to open the indicator, or null to leave it closed. The returned status becomes data-status, and the Value part shows value when it is not null and label otherwise. Because the snapshot is taken before the action runs, predict the post-action state the way built-in statuses do.

deriveCustomStatus is a JavaScript property with no attribute:

const rates = [0.5, 1, 1.5, 2];
const indicator = document.querySelector("media-status-indicator");

function getNextRate(rate = 1) {
  const index = rates.indexOf(rate);

  return rates[Math.min(index + 1, rates.length - 1)] ?? rate;
}

indicator.deriveCustomStatus = (event, snapshot) =>
  event.action === "stepRate"
    ? { status: "rate-up", label: `${getNextRate(snapshot.playbackRate)}×`, value: null }
    : null;

Styling

Attribute	Values	Description
`data-open`	Present / absent	Present while the indicator is open
`data-status`	`"play"`, `"pause"`, `"volume-off"`, `"volume-low"`, `"volume-high"`, `"captions-on"`, `"captions-off"`, `"fullscreen"`, `"exit-fullscreen"`, `"pip"`, `"exit-pip"`, or a custom status	Predicted status for the handled action
`data-starting-style`	Present / absent	Present during the open transition
`data-ending-style`	Present / absent	Present during the close transition

Use data-status to select an icon or other visual treatment, and use the transition attributes for entry and exit styles.

media-status-indicator[data-status="play"] {
  color: green;
}

media-status-indicator[data-starting-style],
media-status-indicator[data-ending-style] {
  opacity: 0;
}

Accessibility

<media-status-indicator> is visual feedback and does not create a live region. Keep every action available through keyboard-operable controls, and pair the player with <media-status-announcer> when state changes should be announced to screen readers. Do not make <media-status-indicator-value> a live region.

Examples

Basic Usage

Focus the player, then press K to play or pause, M to mute, F for fullscreen, C for captions, or I for picture-in-picture.

Focus the player · K: play/pause · M: mute · F: fullscreen · C: captions · I: picture-in-picture

<video-player>
  <media-container class="html-status-indicator-basic" tabindex="0">
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop>
      <track kind="captions" src="/docs/demos/captions-button/captions.vtt" srclang="en" label="English" />
    </video>
    <p class="html-status-indicator-basic__instructions">
      Focus the player · K: play/pause · M: mute · F: fullscreen · C: captions · I: picture-in-picture
    </p>
    <media-status-indicator
      class="html-status-indicator-basic__indicator"
      actions="togglePaused toggleMuted toggleSubtitles toggleFullscreen togglePictureInPicture"
      aria-hidden="true"
    >
      <media-status-indicator-value class="html-status-indicator-basic__value"></media-status-indicator-value>
    </media-status-indicator>
    <media-hotkey keys="k" action="togglePaused"></media-hotkey>
    <media-hotkey keys="m" action="toggleMuted"></media-hotkey>
    <media-hotkey keys="f" action="toggleFullscreen"></media-hotkey>
    <media-hotkey keys="c" action="toggleSubtitles"></media-hotkey>
    <media-hotkey keys="i" action="togglePictureInPicture"></media-hotkey>
  </media-container>
</video-player>

.html-status-indicator-basic {
  position: relative;
}

.html-status-indicator-basic:focus-visible {
  outline: 3px solid #60a5fa;
  outline-offset: 2px;
}

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

.html-status-indicator-basic__instructions {
  position: absolute;
  top: 10px;
  right: 10px;
  left: 10px;
  padding: 6px 10px;
  margin: 0;
  color: white;
  text-align: center;
  background: rgb(0 0 0 / 70%);
  border-radius: 4px;
}

.html-status-indicator-basic__indicator {
  position: absolute;
  top: 50%;
  left: 50%;
  display: grid;
  min-width: 92px;
  padding: 16px;
  color: white;
  pointer-events: none;
  background: rgb(0 0 0 / 72%);
  border-radius: 12px;
  place-items: center;
  transform: translate(-50%, -50%);
  transition:
    opacity 160ms ease-in-out,
    scale 160ms ease-in-out;
}

.html-status-indicator-basic__indicator::before {
  font-size: 28px;
  font-weight: 700;
  line-height: 1;
}

.html-status-indicator-basic__indicator[data-status="play"]::before {
  content: "▶";
}

.html-status-indicator-basic__indicator[data-status="pause"]::before {
  content: "Ⅱ";
}

.html-status-indicator-basic__indicator[data-status="volume-off"]::before {
  content: "🔇";
}

.html-status-indicator-basic__indicator[data-status="volume-low"]::before {
  content: "🔉";
}

.html-status-indicator-basic__indicator[data-status="volume-high"]::before {
  content: "🔊";
}

.html-status-indicator-basic__indicator[data-status="captions-on"]::before,
.html-status-indicator-basic__indicator[data-status="captions-off"]::before {
  content: "CC";
}

.html-status-indicator-basic__indicator[data-status="captions-off"]::before {
  text-decoration: line-through;
}

.html-status-indicator-basic__indicator[data-status="fullscreen"]::before {
  content: "⛶";
}

.html-status-indicator-basic__indicator[data-status="exit-fullscreen"]::before {
  content: "⊠";
}

.html-status-indicator-basic__indicator[data-status="pip"]::before,
.html-status-indicator-basic__indicator[data-status="exit-pip"]::before {
  content: "▣";
}

.html-status-indicator-basic__indicator[data-status="exit-pip"]::before {
  text-decoration: line-through;
}

.html-status-indicator-basic__indicator[data-starting-style],
.html-status-indicator-basic__indicator[data-ending-style] {
  opacity: 0;
  scale: 0.85;
}

.html-status-indicator-basic__value {
  margin-top: 8px;
  font-variant-numeric: tabular-nums;
}

import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/hotkey';
import '@videojs/html/ui/status-indicator';
import '@videojs/html/ui/status-indicator-value';

API Reference

media-status-indicator

Props

Prop	Type	Default
`actions`	`readonly InputAction[]`	—
Description Input actions allowed to open the indicator. All supported actions are allowed when omitted.
`closeDelay` attribute `close-delay`	`number`	—
Description Delay in milliseconds before the indicator closes.
`deriveCustomStatus` attribute `derive-custom-status`	`function`	—
Description Derives display details for custom actions. Called only when the built-in derivation returns `null`; return `null` to leave the indicator closed. Type `((event: InputActionEvent, snapshot: MediaSnapshot) => StatusDetails<IndicatorStatus> \| null)`

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 indicator is open.
`generation`	`number`
Description Increments each time a supported input action updates the indicator.
`status`	`'pause' \| 'play' \| 'volume-off' \| 'vo...`
Description Visual status for the handled input action. Type `'pause' \| 'play' \| 'volume-off' \| 'volume-low' \| 'volume-high' \| 'captions-on' \| 'captions-off' \| 'fullscreen' \| 'exit-fullscreen' \| 'pip' \| 'exit-pip' \| string & {} \| null`
`label`	`string \| null`
Description Translated label for the predicted status.
`value`	`string \| null`
Description Predicted volume percentage for volume actions, otherwise `null`.

Data attributes

Attribute	Type	Details
`data-open`	—
Description Present while the indicator is open.
`data-status`	`'pause' \| 'play' \| 'volume-off' \| 'vo...`
Description Predicted visual status for the handled input action. Type `'pause' \| 'play' \| 'volume-off' \| 'volume-low' \| 'volume-high' \| 'captions-on' \| 'captions-off' \| 'fullscreen' \| 'exit-fullscreen' \| 'pip' \| 'exit-pip' \| string & {} \| null`
`data-starting-style`	—
Description Present during the open transition.
`data-ending-style`	—
Description Present during the close transition.