Overview

The React package exports a small set of public hooks for custom player UI. These hooks are player-scoped: they read state from an enclosing <VideoPlayer> provider.

The new Lit-backed <Video> is a self-contained custom element and does not automatically register with the React player scope. The hooks below are intended for custom controls built around the VideoPlayer scope (for example, a raw <video> element or a future React wrapper that participates in the scope). For the current Lit Video wrapper, use onRixlAnalytics to observe events.

Recommended Pattern

Wrap the media element and its controls in a <VideoPlayer> scope:

import {VideoPlayer, usePlayback} from "@rixl/media-react";

function CustomControls() {
  const {paused, togglePlay} = usePlayback();

  return (
    <button type="button" onClick={() => void togglePlay()}>
      {paused ? "Play" : "Pause"}
    </button>
  );
}

function PlayerPage() {
  return (
    <VideoPlayer>
      <CustomControls />
      {/* A media element that participates in this scope */}
    </VideoPlayer>
  );
}

useGlobalPlayerSettings() is the only page-level hook that intentionally fans out to all mounted scopes.

Choose a Hook

Hook	Use it for	Notes
`useMediaSettings()`	Mute, unmute, volume, and previous volume	Player-scoped audio only
`usePlayback()`	Play, pause, playback rate, loading, ended, `pauseOthers()`	Best for transport controls
`usePlayerProgress()`	Current time, duration, buffered progress, seeking	Preferred public timeline hook
`usePlayerUI()`	Fullscreen, Picture-in-Picture, controls visibility	Exposes durable chrome state only
`usePlayerTracks()`	Audio track and subtitle track selection	Track styling and global caption prefs stay elsewhere
`useGlobalPlayerSettings()`	Page-level coordination across mounted players	Advanced API for shared controls
`useProgressBar({video})`	Low-level drag handling for a raw `HTMLVideoElement`	Prefer `usePlayerProgress()` with `Video`

Which Hook Should Most Apps Start With?

Start with usePlayback() for play-pause UI.
Add usePlayerProgress() for a custom timeline or seek buttons.
Add useMediaSettings() for mute and volume controls.
Add usePlayerTracks() only if your videos expose audio or subtitle track choices.
Use useGlobalPlayerSettings() only when one page-level control should affect several mounted players.

Analytics with the Lit Video Wrapper

If you are using the current Lit Video component, capture events instead of calling scope actions:

import {Video} from "@rixl/media-react";

<Video id="your-video-id" analytics={true} analyticsPage="standalone" onRixlAnalytics={(e) => console.log(e.detail.event)} />;

Recommended Pattern

Choose a Hook

Which Hook Should Most Apps Start With?

Analytics with the Lit Video Wrapper

Related Docs

Auf dieser Seite