Skip to content
FrameworkStyle

Poster

Poster image component that displays a thumbnail until video playback starts

Anatomy

<Poster />

Behavior

The poster shows before playback starts. Once the user plays or seeks, it hides; pausing does not bring it back. Loading a new source shows it again.

You can set the poster URL on the player. This is useful when you want to change the poster from inside a skin, or keep all your media metadata in one place:

<VideoPlayer poster="poster.jpg" />

Supply your own image

The component fills in a source only when you leave one out. srcset, sizes, loading, <picture>, and framework image components all stay available.

The component is the <img>, so image attributes go straight on it:

<Poster srcSet="poster-480.jpg 480w, poster-1080.jpg 1080w" sizes="100vw" />

To render something else, use render. It receives the poster URL as src, undefined until one resolves:

<Poster
  render={({ src, ...props }: ComponentProps<'img'>) =>
    src ? <Image {...props} src={src} alt="" fill /> : null
  }
/>

Inside a skin, pass the same function as renderPoster. The skin draws your image in place of its own:

<VideoSkin
  renderPoster={({ src, ...props }: ComponentProps<'img'>) =>
    src ? <Image {...props} src={src} alt="" fill /> : null
  }
/>

A skin styles the <img> it draws directly. Render something that is not an <img> and its sizing is yours.

Styling

Attribute Values Description
data-visible Present / absent Present before playback starts
data-loading Present / absent Present while the image is fetching
data-loaded Present / absent Present once the image has loaded
data-error Present / absent Present when the image failed

The three load attributes track the image on screen, including one you supplied yourself.

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

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

Accessibility

Unlike the native <video poster> attribute, this component lets you describe the poster for screen readers.

The image is decorative by default (alt=""), since a URL says nothing about what the image shows. When the poster carries meaning, say so:

<Poster alt="Keynote speaker at a conference" />

Whether a poster is informative or decorative is your judgment, per the WAI guidelines.

Examples

Basic Usage

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

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

export default function BasicUsage() {
  return (
    <Player poster="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg">
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline />

        <Poster className="media-poster" />

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

API Reference

Props

PropTypeDefaultDetails
srcstring—

State

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

PropertyTypeDetails
visibleboolean
srcstring
loadingboolean
loadedboolean
errorboolean

Data attributes

AttributeTypeDetails
data-visible
data-loading
data-loaded
data-error