Media

Media Visibility

This component is used to manage media state as page or viewport visibility changes.

# Import

        import '@vidstack/player/define/vds-media-visibility.js';

      

        <script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@vidstack/player@next/cdn/define/vds-media-visibility.js"
></script>

      

# Usage

The <vds-media-visibility> component can be used to manage the playback/volume state of a provider as page/viewport visibility changes. The Intersection Observer API and Page Visibility API are used to detect visibility changes, including minimizing the browser window, device sleep, changing tabs, or scrolling the provider in and out of view.

# Viewport Visibility

You can perform actions on a provider as media enters or exits the browser's visual viewport:

          
1
2
3
4
5
6
7
8
		    

• In the preview above, we're playing media as it enters the viewport and pausing it as it leaves. Currently, other actions include muting mute and unmuting unmute.
• The intersectionThreshold property indicates what percentage of the player must be in the viewport to be considered visible (e.g., 1 = 100%, 0.5 = 50%, etc.).
• You can add a slight delay to when the entry action is performed by using the viewportEnterDelay property. Setting a delay helps avoid jittery state changes as the user scrolls (i.e., rapidly playing/pausing media).

# Viewport Change Event

You can listen to the vds-media-visibility-change event to be notified of any changes to viewport visibility of the provider like so:

# Page Visibility

Similarly to the actions you can take on viewport visibility changes, you can perform them on a provider as page visibility changes:

          
1
2
3
4
5
6
7
8
		    

• In the preview above, we're playing media as it enters the page and pausing it as it exits. Currently, other actions include muting mute and unmuting unmute.
• You can add a slight delay to when the entry action is performed by using the pageEnterDelay property. Setting a delay creates a smoother experience by avoiding jittery state changes as the user changes browser tabs.
• The pageChangeType property refers to the type of hidden state that will trigger the entry and exit actions. It can be set to state or visibility. We'll explain the difference in the next section.

# Page State vs. Visibility

Page state and visibility can be confusing as they're vague terms. Page state here refers to the page lifecycle state, and page visibility refers to the document's visibility.

The page state can be one of the following values:

• active: A page is in the active state if it is visible and has input focus.
• passive: A page is in the passive state if it is visible and does not have input focus.
• hidden: A page is in the hidden state if it is not visible.

In addition, page visibility can be one of the following values:

• visible: The page content may be at least partially visible. In practice, this means that the page is the foreground tab of a non-minimized window.
• hidden: The page content is not visible to the user. In practice, this means that the document is either a background tab, part of a minimized window, or the OS screen lock is active.

You'll generally want to use state as it refers to completely visible or not. Page state also helps differentiate between active and passive states based on input focus. In contrast, visibility refers to partially visible or not.

In summary, use visibility if you want media to keep playing as the user jumps between applications and keeps the page tab active; or, use state if you'd like to pause if the user moves away from the page in any way.

# Page Change Event

You can listen to the same vds-media-visibility-change event to be notified of any page visibility changes of the provider like so: