Quick start

Render a Moviie video in a React app with the provider, the hook, and the component.

Before you begin

You need:

A Moviie account and a publishable API key (mvi_pub_*).
An embed UUID for the video you want to play.
React 19+ (and react-dom 19+).

Create a publishable key under Organization Settings → API Keys at app.moviie.ai, then set it as an environment variable. For a Next.js app:

# .env.local
NEXT_PUBLIC_MOVIIE_PUBLISHABLE_KEY=mvi_pub_your_key_here

Never use a secret key on the client: only mvi_pub_* keys are valid here.

1. Install and import the stylesheet

pnpm add @moviie/player-react

import "@moviie/player-react/styles.css"

See Installation for details.

Wrap your app (or the relevant subtree) in <MoviieProvider>, then use useMoviiePlayer({ embedId }) and spread the result onto <MoviieVideo>. In a Next.js App Router app, the player is a client component:

// app/watch/[embedId]/player.tsx
"use client"
import { MoviieProvider, MoviieVideo, useMoviiePlayer } from "@moviie/player-react"

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

export function Watch({ embedId }: { embedId: string }) {
  return (
    <MoviieProvider publishableKey={process.env.NEXT_PUBLIC_MOVIIE_PUBLISHABLE_KEY!}>
      <Player embedId={embedId} />
    </MoviieProvider>
  )
}

That is the full setup. HLS playback, default controls, captions, chapters, audio tracks, variants, the AI menu, CTAs, the social-DRM watermark for private videos, telemetry, and access gating all work out of the box, honoring the embed's dashboard configuration.

3. Control it from your code (optional)

Attach a ref to get the imperative MoviiePlayerHandle, and subscribe to events with useMoviieEvent:

"use client"
import { useState } from "react"
import {
  MoviieVideo,
  useMoviiePlayer,
  useMoviieEvent,
} from "@moviie/player-react"
import type { MoviiePlayerHandle } from "@moviie/player-react"

function Player({ embedId }: { embedId: string }) {
  const moviie = useMoviiePlayer({ embedId })
  const [handle, setHandle] = useState<MoviiePlayerHandle | null>(null)

  useMoviieEvent(handle, "ended", () => console.log("done"))

  return (
    <>
      <MoviieVideo {...moviie} onReady={setHandle} aspectRatio={16 / 9} />
      <button onClick={() => handle?.play()}>Play</button>
      <button onClick={() => handle?.openSummary()}>Summary</button>
    </>
  )
}

The handle's methods, events, and properties are the same vocabulary as the Expo player and the window.Moviie Player API. See the API reference.

ref vs onReady

The imperative handle is created once the player is ready. Use onReady (as above) or a ref on <MoviieVideo> to receive it; useMoviieEvent takes the handle directly and re-binds when it changes.

4. Override the dashboard configuration (optional)

By default the player honors the embed's dashboard settings. Any setting can be overridden through props:

<MoviieVideo
  {...moviie}
  autoplay={false}
  accentColor="brand"
  controls={{ showChapters: false }}
/>

See Configuration for the full list of presentation props and the API-config-vs-prop-override rule.

Quick start

Before you begin

1. Install and import the stylesheet

2. Render the player

3. Control it from your code (optional)

4. Override the dashboard configuration (optional)

On this page