Media · Gutenberg
Background Video block for WordPress
A looping autoplay background video section with overlay and InnerBlocks content — distinct from video players or popups.
Get Blockenberg
Free Gutenberg block in Blockenberg. The inspector controls and front-end behavior on this page come from this block’s source, not a shared stub.
What it actually does
A looping autoplay background video section with overlay and InnerBlocks content — distinct from video players or popups.
Inspector panels on this block: Video Source, Playback, Overlay, Layout. Those titles come from index.js, not from a shared template.
Behavior controls: “Video Type” options: Self-Hosted (MP4/WebM), YouTube, Vimeo; “YouTube ID or URL” (Paste the full URL or just the video ID); “Vimeo ID or URL” (Paste the full URL or just the numeric ID); “Object Fit” options: Cover, Contain, Fill.
Where to find it
Gutenberg inserter → Media → search “Background Video” (block name `blockenberg/background-video` in block.json). Style it in the sidebar after insert.
How to use Background Video block for WordPress
- Install Blockenberg. Install from WordPress.org and activate the plugin.
- Insert the block. Edit a page, click +, search for “Background Video”, insert it. Category: Media.
- Configure inspector controls that exist on this block. Open Video Source. Set “Video Type”, “YouTube ID or URL”, “Vimeo ID or URL”, “Object Fit”.
- Check the published page. The view script reads HTML data attributes: data-in-view, data-loop, data-object-fit, data-object-pos, data-pause-hover, data-rate, data-video-type, data-video-url. The block editor preview may not run the same view script.
Inspector controls from this block’s code
| Control | What the code does |
|---|---|
| Video Type | Select control; the chosen value is saved on the block. Options: Self-Hosted (MP4/WebM); YouTube; Vimeo. block.json default: hosted. Saved as `videoType`. |
| YouTube ID or URL | Text field in the inspector. Paste the full URL or just the video ID. Saved as `youtubeId`. |
| Vimeo ID or URL | Text field in the inspector. Paste the full URL or just the numeric ID. Saved as `vimeoId`. |
| Object Fit | Select control; the chosen value is saved on the block. Options: Cover; Contain; Fill. block.json default: cover. Saved as `objectFit`. |
| Object Position | Select control; the chosen value is saved on the block. Options: Center; Top; Bottom; Left; Right. block.json default: center center. Saved as `objectPosition`. |
| Loop | On/off toggle in the inspector. On by default. Saved as `videoLoop`. |
| Play only when in viewport | On/off toggle in the inspector. On by default. Saved as `playOnlyInView`. |
| Pause on hover | On/off toggle in the inspector. Off by default. Saved as `pauseOnHover`. |
| Playback Speed | Numeric range control in the inspector. Range 0.25–2. block.json default: 1. Saved as `playbackRate`. |
| Overlay Opacity (%) | Numeric range control in the inspector. Range 0–100. block.json default: 45. Saved as `overlayOpacity`. |
| Gradient Overlay | On/off toggle in the inspector. Off by default. Saved as `overlayGradient`. |
| Direction | Select control; the chosen value is saved on the block. Options: Top → Bottom; Bottom → Top; Left → Right; Right → Left; Diagonal ↘; Diagonal ↗. block.json default: to bottom. Saved as `overlayGradientDir`. |
| Min Height (px) | Numeric range control in the inspector. Range 100–1200. block.json default: 600. Saved as `minHeight`. |
| Padding Top | Numeric range control in the inspector. Range 0–300. block.json default: 80. Saved as `paddingTop`. |
| Padding Bottom | Numeric range control in the inspector. Range 0–300. block.json default: 80. Saved as `paddingBottom`. |
| Padding Left | Numeric range control in the inspector. Range 0–200. block.json default: 24. Saved as `paddingLeft`. |
| Padding Right | Numeric range control in the inspector. Range 0–200. block.json default: 24. Saved as `paddingRight`. |
| Content Max Width (px) | Numeric range control in the inspector. Range 200–1600. block.json default: 860. Saved as `contentMaxWidth`. |
| Horizontal Align | Select control; the chosen value is saved on the block. Options: Left; Center; Right. block.json default: center. Saved as `contentAlign`. |
| Vertical Align | Select control; the chosen value is saved on the block. Options: Top; Middle; Bottom. block.json default: center. Saved as `contentVAlign`. |
| Border Radius (px) | Numeric range control in the inspector. Range 0–80. block.json default: 0. Saved as `borderRadius`. |
| Overlay Color | Color control in the inspector. block.json default: #000000. Saved as `overlayColor`. |
| Gradient Start | Color control in the inspector. block.json default: #000000. Saved as `overlayGradientStart`. |
| Gradient End | Color control in the inspector. block.json default: transparent. Saved as `overlayGradientEnd`. |
| Content Text Color | Color control in the inspector. block.json default: #ffffff. Saved as `textColor`. |
What the front-end script actually does
- The view script reads HTML data attributes: data-in-view, data-loop, data-object-fit, data-object-pos, data-pause-hover, data-rate, data-video-type, data-video-url.
- An IntersectionObserver starts work when the block enters the viewport.
When this is the right block
- A looping autoplay background video section with overlay and InnerBlocks content — distinct from video players or popups — that is the job of Background Video, not a generic content block.
- Use it when you need the editor control labeled “Video Type”, which exists on this block’s inspector.
- It matches pages about video, background, loop.
- Inserter grouping: video, animation, and rich media sections.
Notes from the implementation
viewScript: this folder’s frontend.js is enqueued on the front end for this block.
FAQ
How do I add the Background Video block in WordPress?
Install Blockenberg from WordPress.org, edit a page in the block editor, click +, and search for “Background Video”. It sits under Media. After insert, open Video Source and set “Video Type”, “YouTube ID or URL”, “Vimeo ID or URL”, “Object Fit”.
What makes Background Video different from other Blockenberg blocks?
A looping autoplay background video section with overlay and InnerBlocks content — distinct from video players or popups. Inspector labels on this block include “Video Type”, “YouTube ID or URL”, “Vimeo ID or URL”, “Object Fit”.
Is the Background Video Gutenberg block free?
Yes. Background Video ships inside Blockenberg. Get the plugin from WordPress.org — no paid add-on is required for this block.
Can I style Background Video to match my theme?
Yes. Blockenberg’s shared typography and color panels apply here, plus any block-specific style controls listed on this page (panels: Video Source, Playback, Overlay, Layout).
Related media blocks
Sticky Video
Video player that minimises into a floating corner player when scrolled past, with close and restore controls.
Video Facade
Performance-optimized video thumbnail that loads the actual YouTube or Vimeo player only on click. Eliminates heavy iframes on page load, improving Core Web Vitals. Supports custom thumbnails, overlay text, and animated play buttons.
Video Grid
Responsive grid of video cards with play-in-lightbox functionality. Supports YouTube, Vimeo, and self-hosted videos. Custom thumbnails, titles, and duration badges.
Video Playlist
A video player paired with a clickable episode/chapter list — perfect for course previews, tutorial series and video podcasts.
Video Popup Button
A stylizable play button that opens a YouTube, Vimeo, or custom video in a modern full-screen popup modal.
Embed / iFrame
Responsive iframe embed for Calendly, Typeform, Google Forms, Airtable, YouTube, Vimeo, or any URL. Full aspect-ratio control and loading options.
Get Blockenberg
Install Blockenberg from WordPress.org, then insert Background Video from the Gutenberg inserter.