react-poster-video

Autoplay hero video that doesn't ruin your site.

A tiny (~1 component, zero runtime deps) React component for cover/hero video that treats motion as a progressive enhancement, not the baseline:

• 🖼️ The poster image is the real header. It's the SSR markup and paints instantly. The muted loop fades in on top only once it can genuinely play — so a slow connection, a decode failure, or a blocked autoplay just leaves the photo. No black flash, no layout shift, no broken state.
• ♿ Respects prefers-reduced-motion. The video never even mounts for those users. Accessibility-first, not bolted on.
• 🔋 Plays only when on-screen (IntersectionObserver) and pauses when the tab is hidden — no off-screen video draining battery and bandwidth.
• 🤝 Survives the React autoplay footgun (the one everyone hits — see below).
• 🧩 Works in the Next.js App Router (ships the "use client" directive).

npm i react-poster-video

import { PosterVideo } from 'react-poster-video';

<PosterVideo
  poster="/hero/fountain-poster.jpg"
  src="/hero/fountain.mp4"
  alt="A stone fountain welling over basalt"
  style={{ aspectRatio: '16 / 9' }}
/>;

Multiple codecs, a custom crop, and overlay content:

<PosterVideo
  poster="/hero/falls-poster.jpg"
  sources={[
    { src: '/hero/falls.webm', type: 'video/webm' },
    { src: '/hero/falls.mp4', type: 'video/mp4' },
  ]}
  objectPosition="70% 40%"
  crossfadeMs={800}
  style={{ height: 480 }}
>
  <h1 style={{ position: 'relative', color: 'white' }}>Where strangers become regulars</h1>
</PosterVideo>

The React autoplay footgun

Browsers only allow autoplay for muted video. The catch: React's JSX muted prop can render as an attribute without setting the DOM .muted property — and the browser checks the property. So <video muted autoPlay> frequently gets its play() rejected, and you ship a black box.

react-poster-video sets .muted = true on the element imperatively and calls .play() itself, swallowing the rejection so the poster simply stays if autoplay is still refused:

const v = videoRef.current;
v.muted = true;                 // the property, not just the attribute
v.play().then(reveal).catch(() => {/* poster stays — no broken state */});

That single detail is the difference between a hero that "sometimes doesn't play" and one that's reliable.

Props

| Prop | Type | Default | | | --- | --- | --- | --- | | poster | string | — | Required. The static header image (paints instantly). | | src | string | — | A single MP4 source. | | sources | { src; type? }[] | — | Multiple sources (webm + mp4). Wins over src. | | alt | string | '' | Poster alt text. | | className / style | | | Applied to the wrapper. Set sizing here (aspectRatio/height). | | objectFit | CSSProperties['objectFit'] | 'cover' | Fit for poster + video. | | objectPosition | string | — | Crop position, e.g. "70% 40%". | | crossfadeMs | number | 600 | Fade-in once the video plays. | | loop | boolean | true | Loop playback. | | playWhenVisible | boolean | true | Play only while on-screen. | | rootMargin | string | '200px' | IntersectionObserver margin. | | respectReducedMotion | boolean | true | Skip video for reduced-motion users. | | onReady | () => void | — | Fires when the video is playing + revealed. | | children | ReactNode | — | Overlay content (gradients, headings, CTAs). | | videoProps | VideoHTMLAttributes | — | Passthrough to the <video>. |

The wrapper is position: relative; overflow: hidden; the poster and video are absolutely positioned to fill it. You control the size via style/className.

Encoding the loop (the other half people get wrong)

A good hero loop is muted, web-optimized, and small. Strip the audio track, cap the size, and move the moov atom up front for fast start. ffmpeg:

# MP4 (H.264) — broad support, audio stripped, fast-start
ffmpeg -i source.mov -an -vf "scale=1600:-2" -c:v libx264 -profile:v high \
  -crf 24 -preset slow -movflags +faststart hero.mp4

# WebM (VP9) — smaller; offer it first, fall back to MP4
ffmpeg -i source.mov -an -vf "scale=1600:-2" -c:v libvpx-vp9 \
  -crf 33 -b:v 0 hero.webm

# Poster frame (grab a representative still ~1s in)
ffmpeg -i source.mov -ss 00:00:01 -frames:v 1 -q:v 3 hero-poster.jpg

Tips: keep loops short (a few seconds) and pick subjects where motion is the point — water, fire, steam, drifting clouds. A frozen frame of those reads as inert; almost everything else is better served by a plain image.

License

MIT © Hottub, Inc.