API

Fullscreen

In this section, we'll look at how to request and track fullscreen changes with Vidstack Player.

# Methods

You can request to enter or exit fullscreen on the <media-player> element like so:

        try {
  await player.enterFullscreen();
} catch (e) {
  // This will generally throw if:
  // 1. Fullscreen API is not available.
  // 2. Or, the user has not interacted with the document yet.
}

      

        try {
  await player.exitFullscreen();
} catch (e) {
  // This will generally throw if:
  // 1. Fullscreen API is not available.
}

      

# Target

By default, calling the enterFullscreen() method will first attempt to use the Fullscreen API so the custom media UI is displayed, otherwise it'll fallback to the current media provider.

You can specify that you only want to display the provider in fullscreen and not the entire media by specifying the fullscreen target like so:

        // Accepts `prefer-media`, `media`, `provider`
player.enterFullscreen('provider');

      

# Media Store

The following fullscreen properties are available on the media store:

• canFullscreen: Whether fullscreen API is currently available.
• fullscreen: Whether the player is currently in fullscreen mode.

# Media Remote

The media remote provides methods for dispatching media-enter-fullscreen-request and media-exit-fullscreen-request request events like so:

# Styling

The following media attributes are available for styling based on the current fullscreen state:

        media-player[data-can-fullscreen] {
  /* fullscreen API is available. */
}

media-player:not([data-can-fullscreen]) {
  /* fullscreen API is _not_ available. */
}

media-player[data-fullscreen] {
  /* fullscreen is active. */
}

media-player:not([data-fullscreen]) {
  /* fullscreen is _not_ active. */
}

      

# Events

The following events are available for detecting fullscreen changes or errors:

# Screen Orientation

The player uses the native Screen Orientation API to lock the document's orientation. You can specify the preferred fullscreen orientation like so:

This will lock the screen orientation as specified by fullscreen-orientation while the media enters fullscreen, and it will be unlocked while exiting. Read more about the available screen orientation types.

# Events

The following events are available for detecting screen orientation changes: