Skip to content
FrameworkStyle

useMedia

Hook to access the media object from within a Player

Import

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

useMedia returns the media object attached to the current player. It returns null until the media mounts. Call it inside the matching Player.

The media object may be an HTMLVideoElement or a Video.js media object that controls one. It always provides play(). Check isMediaPauseCapable(media) before using pause() because lightweight media implementations do not have to provide it.

With a packaged preset, import useMedia from @videojs/react. With a player made by createPlayer, use the useMedia hook returned by that call. It is connected to the new player’s context.

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

Choose between useMedia and a ref

A React ref on <MuxVideo> or <HlsJsVideo> receives the rendered HTMLVideoElement. useMedia() receives the Video.js media object attached to the player. Use the ref for browser video APIs. Use useMedia() for Video.js properties such as streamType and targetLiveWindow.

To attach your own media object, see useMediaAttach.

import { isMediaLiveCapable, isMediaStreamTypeCapable, useMedia } from '@videojs/react';

export function LiveDetails() {
  const media = useMedia();
  if (!media) return null;

  const streamType = isMediaStreamTypeCapable(media) ? media.streamType : 'unknown';
  const targetLiveWindow = isMediaLiveCapable(media) ? media.targetLiveWindow : Number.NaN;

  return <output>{streamType}: {String(targetLiveWindow)}</output>;
}

Access hls.js

Media backed by hls.js also provides an engine property. That property is specific to hls.js, so keep direct engine calls in a small part of your app rather than treating them as part of the common Media API.

Examples

Basic Usage

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

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

function MediaInfo() {
  const media = useMedia();
  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

Return Value

Media | null