Skip to content

ReferencePlayer

useMedia

Hook to access the media attached to the nearest Player

useMedia returns the media attached to the nearest Player, or null until a media component mounts inside it.

Import

import { useMedia } from "@videojs/react";

createPlayer also returns useMedia alongside Player and usePlayer:

const { Player, usePlayer, useMedia } = createPlayer({ features: videoFeatures });

Both forms are the same hook and return the same Media | null type. Unlike usePlayer, the createPlayer form doesn’t add typing from your features.

Usage

Call useMedia from a component rendered inside Player. Calling it outside Player throws, because it reads the nearest Player’s context.

import { isMediaSeekCapable, useMedia } from "@videojs/react";

export function PlayFromStart() {
  const media = useMedia();

  function playFromStart() {
    if (isMediaSeekCapable(media)) media.currentTime = 0;
    media?.play();
  }

  return <button onClick={playFromStart}>Play from start</button>;
}

The component re-renders when a different media attaches or the current one detaches, not when the media’s own properties change. To render from playback state, such as paused or currentTime, select it with usePlayer.

The Media object

Media is the player’s handle on whatever plays the content. What that handle is depends on the media component:

  • Video and Audio attach the rendered native <video> or <audio> element.
  • Components that front a playback engine or an embed, such as HlsVideo, DashVideo, or YouTubeVideo, attach an object that implements the media contract on top of that engine.

Because media vary this much, the Media type guarantees only a play() method and the addEventListener, removeEventListener, and dispatchEvent event methods. Everything else, like pausing, seeking, volume, or text tracks, is a capability that a given media may or may not have. Narrow Media with the media capability guards before using those members.

Examples

Basic usage

Read the attached media’s source and video dimensions, narrowing with isMediaSourceCapable and isMediaVideoDimensionsCapable first.

import { Container, createPlayer, isMediaSourceCapable, isMediaVideoDimensionsCapable } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player, useMedia, usePlayer } = createPlayer({
  features: videoFeatures,
});

function MediaInfo() {
  const media = useMedia();

  // `useMedia` re-renders only when the media changes; subscribe to `canPlay` so the values below refresh once loaded.
  usePlayer((state) => state.canPlay);

  if (!media) return null;

  return (
    <dl className="info-panel">
      {isMediaSourceCapable(media) && (
        <div>
          <dt>src</dt>
          <dd>{media.currentSrc || '—'}</dd>
        </div>
      )}
      {isMediaVideoDimensionsCapable(media) && (
        <>
          <div>
            <dt>videoWidth</dt>
            <dd>{media.videoWidth}px</dd>
          </div>
          <div>
            <dt>videoHeight</dt>
            <dd>{media.videoHeight}px</dd>
          </div>
        </>
      )}
    </dl>
  );
}

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <MediaInfo />
      </Container>
    </Player>
  );
}

API Reference

useMedia(): Media | null

Return Value

PropertyTypeDetails
playfunction
addEventListener(<K extends keyof Events & string>(ty...
removeEventListener(<K extends keyof Events & string>(ty...
dispatchEventfunction