1. Core Concepts
  2. Events

Core Concepts


In this section, we'll look at the rich event system that's available when working with the player.

Media Events

The media element fires a superset of HTMLMediaElement events:

  • play -> onPlay
  • canplay -> onCanPlay
  • loadedmetadata -> onLoadedMetadata

Prefer our events over the native media element events (e.g., <video>) as they smooth out any unexpected behaviour across browsers, attach additional metadata to the event detail, and contain rich information such as the request event that triggered it or the origin event that kicked it off.


Request Events

Request events are fired when 'requesting' the controller to update the provider's state. For example, the media-play-request event is a request to begin/resume playback, and as a consequence it'll trigger a play() call. The provider should respond with a play event to confirm the request was satisfied.


Event Triggers

All events in the library keep a history of trigger events which are stored as a chain. Each event points to the event that came before it all the way up to the origin event. The following is an example of a chain that is created when the play button is clicked:

playing (vidstack)
playing (native)
play (vidstack)
play (native)
pointerup (origin)

Event Types

All event types are named using PascalCase and suffixed with the word Event (e.g., SliderDragStartEvent). Furthermore, media events are all prefixed with the word Media as seen in the example above.

        import {
  type MediaCanPlayEvent,
  type MediaPlayEvent,
  type MediaStartedEvent,
  type MediaTimeUpdateEvent,
} from 'vidstack';