useMediaRegistration

Import

import { useMediaRegistration } from '@videojs/react';

Usage

useMediaRegistration returns a setter function for registering a media element with the player context. The built-in <Video> and <Audio> components use this internally — you only need it when building a custom media element.

import { useMediaRegistration } from '@videojs/react';
import { useRef, useEffect } from 'react';

function CustomMedia({ src }: { src: string }) {
  const setMedia = useMediaRegistration();
  const ref = useRef<HTMLVideoElement>(null);

  useEffect(() => {
    if (ref.current && setMedia) {
      setMedia(ref.current);
      return () => setMedia(null);
    }
  }, [setMedia]);

  return <video ref={ref} src={src} />;
}

Who needs this

You only need useMediaRegistration if you’re replacing the built-in <Video> or <Audio> components with a custom element. Common reasons:

• Wrapping a third-party video player
• Using a <canvas> or WebGL-based renderer
• Building a custom <audio> element with additional markup

For standard <video> and <audio> playback, use the built-in components.

Cleanup pattern

Always return a cleanup function that passes null to the setter. This detaches the media element when the component unmounts, preventing stale references in the store.

Safe outside Provider

Returns undefined when called outside a Player Provider. Check the return value before using it — this avoids crashes in components that may render outside the player tree.