GX Video Background

Native Gutenberg block for video backgrounds with focal-point control, fixed scroll-follow, and InnerBlocks nesting. Compatible with GeneratePress + GenerateBlocks.

Description

• Native block — nest any block(s) inside (paragraphs, headings, GenerateBlocks containers, columns, buttons, etc.)
• Choose video from Media Library or paste an external MP4/WebM URL (https only)
• Optional poster image (used during load, as mobile fallback, and under reduced-motion)
• Height modes: 100vh / 50vh / custom (any CSS unit) / auto — viewport modes use svh with vh fallback so mobile URL-bar resize doesn't jump
• Focal point picker (X/Y %) — controls object-position so the right part of the video stays visible at any size
• Fixed (parallax) scroll-follow mode — uses CSS clip-path to keep the video pinned to the viewport while content scrolls over it
• Overlay color + opacity
• Autoplay / loop / muted / playsinline toggles
• Optional accessible pause/play button (WCAG 2.2.2) — off by default
• Disable-on-mobile mode shows the poster AND aborts the video download to save bandwidth
• Respects prefers-reduced-motion: video hidden and paused, poster shown instead (user can still press play via the pause button)
• Offscreen videos are paused automatically (IntersectionObserver) to save CPU/battery
• Full-width and wide alignment supported

Installation

1. Drop the gx-videobg folder into wp-content/plugins/.
2. Activate from Plugins.
3. Add the Video Background block from the inserter (Design category).

Usage with GenerateBlocks

The block produces a single outer <div class="gx-videobg"> with a stacking context. You can place a generateblocks/element directly inside the content area and it will inherit the layout — use the block's own padding/margin controls for spacing, or set Inner content max-width to constrain content.

Notes on Fixed Mode

Fixed mode uses clip-path: inset(0) on the parent so the inner position: fixed video is clipped to the block's bounding rectangle. This works in all evergreen browsers. On screens ≤ 768px the fixed mode is automatically disabled to avoid iOS Safari rendering quirks.

Accessibility

Background videos are decorative (aria-hidden). Enable Show pause button (Playback panel) to add a 44px pause/play control — recommended whenever autoplay is on, per WCAG 2.2.2. Under prefers-reduced-motion the video is hidden and paused by default; the pause button lets the user opt in to playback. The button is injected by the small frontend script (view.js), so it never renders as a dead control when JavaScript is unavailable.

Changelog

1.1.0

• Added optional accessible pause/play control (injected via viewScript, off by default)
• Reduced-motion now actually stops the video and shows the poster
• Disable-on-mobile now aborts the video download instead of just hiding it
• External video URLs restricted to http(s)/relative; MIME type inferred from URL extension
• Poster URL escaped when embedded in CSS url()
• Viewport height modes use svh with vh fallback
• Background video marked aria-hidden
• Offscreen videos paused via IntersectionObserver
• Forced white text now yields to the block's text-color setting
• Guarded overlay color parser against invalid hex
• Deprecation entry added so 1.0.0 blocks upgrade cleanly

1.0.0

• Initial release