Skip to main content
Poster renders an <img> element that 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.
Requires the playback feature to be registered with the player.

​
Import

import { Poster } from '@videojs/react';

​
Basic Usage

import { Poster } from '@videojs/react';

function Player() {
  return (
    <div className="player-container">
      {/* ... video element ... */}
      <Poster
        src="https://example.com/poster.jpg"
        alt="Preview of the video"
        className="poster"
      />
    </div>
  );
}

​
Props

Poster accepts all standard <img> element props in addition to the following:
​
src
string
URL of the poster image. Passed directly to the underlying <img> element.
​
alt
string
Accessible text alternative for the image. Use an empty string (alt="") to mark the image as decorative.
​
className
string | ((state: Poster.State) => string)
CSS class name or a function that receives state and returns a class name.
​
style
CSSProperties | ((state: Poster.State) => CSSProperties)
Inline style or a function that receives state and returns a style object.
​
render
ReactElement | ((props: HTMLProps, state: Poster.State) => ReactElement | null)
Custom render prop for full element control.

​
State Data Attributes

AttributeDescription
data-visiblePresent when the poster should be shown (before first play or seek).

​
CSS Styling Example

.poster {
  position: absolute;
  inset: 0;
  width: 100%;
  height: 100%;
  object-fit: cover;
  transition: opacity 0.3s;
}

.poster:not([data-visible]) {
  opacity: 0;
  pointer-events: none;
}

​
Accessibility

Unlike the native <video poster> attribute, Poster allows you to provide accessible text alternatives via alt. Describe the image (e.g., alt="Conference keynote speaker") or mark it as decorative with alt="".

Build docs developers (and LLMs) love

Get started for freeTalk to us