Skip to content

ReferencePlayer

usePlayer

Hook to access the player store from within a Player

Import

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

The usePlayer hook returned by createPlayer gives you access to the player store from any component within its Player. It’s typed to the features you passed to createPlayer, and has two overloads — without arguments for direct store access, or with a selector for reactive state subscriptions.

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

The pair works exactly like React Context: Player is the Provider, and usePlayer is its useContext-style consumer, so the calling component must render inside Player. You can still read state anywhere: Player renders no DOM of its own, so lift it above every component that needs player state, the way you’d lift any Provider.

usePlayer is also available as a standalone import (import { usePlayer } from '@videojs/react'), but the standalone version returns an untyped UnknownStore. Pass a premade selector to recover typing:

import { usePlayer, selectPlayback } from '@videojs/react';

usePlayer();               // UnknownStore (state: unknown)
usePlayer(selectPlayback); // MediaPlaybackState | undefined

Examples

Store Access

Call usePlayer() without arguments to get the store instance. Use this for imperative actions like play, pause, and volume changes. The component does not re-render on state changes.

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

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

function Controls() {
  const store = usePlayer();

  return (
    <div className="controls">
      <button type="button" onClick={() => store.play()}>
        Play
      </button>
      <button type="button" onClick={() => store.pause()}>
        Pause
      </button>
    </div>
  );
}

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

Selector Subscription

Pass a selector function to subscribe to specific state. The component re-renders when the selected value changes, using shallow equality by default.

Paused
true
Time
0.0s / 0.0s
import { Container, createPlayer } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

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

function StateDisplay() {
  const state = usePlayer((s) => ({
    paused: s.paused,
    currentTime: s.currentTime,
    duration: s.duration,
  }));

  return (
    <dl className="panel">
      <div>
        <dt>Paused</dt>
        <dd>{String(state.paused)}</dd>
      </div>
      <div>
        <dt>Time</dt>
        <dd>
          {state.currentTime.toFixed(1)}s / {state.duration.toFixed(1)}s
        </dd>
      </div>
    </dl>
  );
}

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

API Reference

Without Selector

usePlayer(): UnknownStore

Access the player store from within a Player.

This standalone hook has no knowledge of your configured features, so it returns an untyped UnknownStore whose state properties are typed as unknown. For typed access, use the usePlayer returned by createPlayer(), or pass a premade selector to recover the type from its return value.

Return Value

PropertyTypeDetails
$stateobject
targetunknown | null
destroyedboolean
stateRecord<string, unknown>
attachfunction
destroyfunction
subscribefunction

With Selector

usePlayer<R>(selector): R

Select a value from the player store. Re-renders when the selected value changes.

The selector receives UnknownState, so an inline selector returns unknown. Pass a premade selector (e.g. selectPlayback) to get a typed result.

Parameters

ParameterTypeDefaultDetails
selector*function—

Return Value

R