close
FrameworkStyle

Poster

Poster image component that displays a thumbnail until video playback starts

Anatomy

Import the component: 

<Poster src="poster.jpg" alt="Video preview" />

Behavior

The poster is visible before playback starts. Once the user plays or seeks, the poster hides permanently — pausing does not bring it back. The poster reappears when a new source is loaded.

Styling

Style the poster with the [data-visible] attribute:

React renders an <img> element. Add a className to style it: 

.poster:not([data-visible]) {
  display: none;
}

You control the child <img> — this means srcset, sizes, loading="lazy", and framework image components all work naturally.

Accessibility

Unlike the native <video poster> attribute, this component allows you to provide accessible text alternatives for screen readers via the alt attribute on your child <img>. This means you can describe the poster image (e.g., alt="Keynote speaker at a conference") or mark it as decorative with alt="" if it doesn’t convey meaningful information.

Examples

Basic Usage

Image
 
import { createPlayer, PlayButton, Poster } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

import './BasicUsage.css';

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

export default function BasicUsage() {
  return (
    <Player.Provider>
      <Player.Container className="react-poster-basic">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline />

        <Poster
          className="react-poster-basic__poster"
          src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg"
        />

        <PlayButton
          className="react-poster-basic__button"
          render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
        />
      </Player.Container>
    </Player.Provider>
  );
}

API Reference

State

State is accessible via the render, className, and style props.

Property Type Details
visible boolean

Data attributes

Attribute Type Details
data-visible