Configure

Background video

Background mode turns a player into decoration: muted, looping, cover-filled, no controls, and paused automatically when it scrolls out of view. It works the same way for an MP4 as it does for a YouTube or Vimeo embed.

A hero that moves

Muted, looping, cover-filled — and paused when you scroll away.

Playback state—

The markup

The wrapper needs a size. Background mode drops the default 16:9 aspect ratio and fills its container instead, so give the container a height.

One attributehtml

<div class="hero">
  <video data-fideo data-fideo-background src="/media/clip.mp4"></video>
  <div class="hero-copy">…</div>
</div>

The container styles you supplycss

.hero {
  position: relative;
  min-height: 70vh;
}

.hero-copy {
  position: relative;
  z-index: 4; /* above the video and its overlay */
}

What background mode forces

These four are switched on regardless of what you passed or what the markup says, because a background video cannot function without them. Browsers will not autoplay an unmuted video, and a decorative video that stops after one pass reads as broken.

Option	Forced to
autoplay	true
muted	true
loop	true
playsInline	true

Two more change their default but stay overridable:

Option	Default in background mode	Override with
controls	false	`data-fideo-controls="true"`
viewport	'play-pause'	`data-fideo-viewport="none"`

Viewport pausing is the reason background video is cheap. A hero that has scrolled past stops decoding entirely, which matters most on the low-powered devices least able to afford it.

Cover sizing

A <video> can simply use object-fit: cover. An iframe cannot, so Fideo measures the wrapper and sizes the frame to overflow it on the short axis, keeping it centred. That maths needs to know the source's aspect ratio.

Non-16:9 sourceshtml

<iframe
  data-fideo
  data-fideo-background
  data-fideo-background-aspect-ratio="9:16"
  src="https://www.youtube.com/shorts/ot-vAzEBxlI"
></iframe>

Provider	How it fills
html5	`object-fit: cover` — the ratio option is not needed
youtube	Measured and sized by Fideo, re-run on resize
vimeo	Measured and sized by Fideo, plus Vimeo's own `background=1`
wistia	Wistia's `fit-strategy="cover"`

Pointer events are disabled on background embeds so clicks reach your own content instead of the provider's frame. Enabling controls on a background player gives them back through the control bar.

Per provider

MP4html

<video data-fideo data-fideo-background src="/media/loop.mp4"></video>

Vimeohtml

<iframe data-fideo data-fideo-background src="https://vimeo.com/347119375"></iframe>

YouTubehtml

<iframe data-fideo data-fideo-background src="https://www.youtube.com/watch?v=pb-j3svRQLI"></iframe>

Wistiahtml

<iframe data-fideo data-fideo-background src="https://fast.wistia.com/embed/medias/358edhd4og"></iframe>

Fullscreen

If you enable controls on a background player, going fullscreen suspends the cover maths and lets the video letterbox normally, then restores cover sizing on exit. Nothing to configure.

Worth knowing

Give the container a height. Background players inherit their box; a container with no height renders a zero-height player.
Add a poster. It covers the gap before the first frame decodes, especially on slow connections.
Keep text legible. Fideo does not add a scrim in background mode — apply your own gradient or overlay.
Respect reduced motion. Consider skipping the video entirely for prefers-reduced-motion: reduce; Fideo does not make that decision for you.

Opting out for reduced motionjs

const calm = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

if (!calm) {
  mountFideo(el, { background: true });
}