API reference

Everything below is exported from @moviie/player-react. The data layer (MoviieClient, playback types, typed errors, telemetry) is re-exported from @moviie/player-sdk, and the contract constants come from @moviie/player-types: this package never re-declares the contract.

<MoviieProvider>

Place at the root of the subtree that renders players. Provides the Moviie client and the viewer-token store.

useMoviieContext() reads the provider value from within the tree.

useMoviiePlayback(args)

Low-level hook that fetches playback metadata for an embed. useMoviiePlayer wraps it; use this directly when you only need the data, not the component.

Arguments

Return value

useMoviiePlayer(options)

The main hook. Fetches playback metadata and returns it ready to spread onto <MoviieVideo>. The Vidstack player instance is created by <MoviieVideo> itself and exposed through the imperative handle (see below).

Options

Return value

const moviie = useMoviiePlayer({ embedId })
return <MoviieVideo {...moviie} aspectRatio={16 / 9} />

useMoviieEvent(handle, event, listener)

Subscribe to a single contract event from React. Pass the handle you received from <MoviieVideo>'s onReady (or a ref's .current); the subscription re-binds when the handle changes and cleans up on unmount.

useMoviieEvent(handle, "timeupdate", ({ currentTime }) => {
  // ...
})

For multiple events, use the onEvent prop on <MoviieVideo> instead.

<MoviieVideo>

The player component. Spread the return value of useMoviiePlayer onto it, plus any presentation overrides.

Playback props

Presentation props

See Configuration for the API-config-vs-prop rule and the full controls flag list.

Callbacks

<MoviieVideo> also accepts a ref of type MoviiePlayerHandle.

<MoviieErrorBoundary>

React error boundary that catches crashes inside the player and keeps them from taking down the host app. <MoviieVideo> already wraps itself in one; use this directly to protect a larger tree or to supply a custom fallback.

See Error handling.

MoviiePlayerHandle

The imperative control surface exposed through the <MoviieVideo> ref (or onReady). It mirrors the window.Moviie JavaScript API and the Expo player: the same methods, events, and properties.

Methods

Grouped by purpose (full signatures in the Methods reference):

handle.play()
handle.seek(30)
handle.openSummary()
const state = handle.getState() // PlayerState (contract shape)

Events

Subscribe with useMoviieEvent(handle, event, listener), the onEvent prop, or handle.on(event, listener). The full event set and payloads are in the Events reference: lifecycle (ready, play, pause, ended, timeupdate, seeking, seeked, volumechange, fullscreenenter, fullscreenexit, pipenter, pipexit, qualitychange, error), CTAs (ctashow, ctahide, ctaclick), and the AI surfaces (searchopen, searchclose, aimenuopen, aimenuclose, quizopen, quizclose, quizcomplete, summaryopen, summaryclose, ebookopen, ebookclose, variantchange).

Properties

Read individual properties off the handle, or call getState() for a coherent snapshot. The full list and types are in the Properties reference: for example currentTime, duration, paused, ended, volume, muted, fullscreen, pip, playbackRate, availableQualities, plus the feature flags searchable, quizzable, summarizable, ebookable, mindMappable, and version.

Contract constants

Re-exported from @moviie/player-types so you can reference contract names without string literals:

import {
  PLAYER_API_METHODS,
  PLAYER_API_PROPERTIES,
  PLAYER_API_VERSION,
} from "@moviie/player-react"

Versioning

@moviie/player-react follows strict semver. It tracks the PLAYER_API_VERSION contract: a breaking change to the contract (a contract MAJOR bump in @moviie/player-types) ships as a corresponding MAJOR bump here. The package never forks or extends the contract locally.