FrameworkStyle

Poster

Poster image component that stays visible until 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: 

media-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 

import { createPlayer, features, PlayButton, Poster, Video } from '@videojs/react';

import './BasicUsage.css';

const Player = createPlayer({ features: [...features.video] });

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

        <Poster
          className="react-poster-basic__poster"
          src="https://image.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/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
visible boolean

Data attributes

Attribute Description
data-visible -
VideoJS