1. Core Concepts
  2. Events

Core Concepts

Events

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

Media Events

The player element fires a superset of HTMLMediaElement events:

  • play -> play
  • canplay -> can-play
  • loadedmetadata -> loaded-metadata

Vidstack media events 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)
media-play-request
pointerup (origin)
null
          
        

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 examples below.

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