Kinetic Video Modal

Overview

Kinetic Video Modal displays a video through a styled preview area containing:

• A cover image
• A dark overlay
• A customizable play button

The actual video player is created only after the visitor activates the play button.

Use the block for:

• Product demonstrations
• Portfolio reels
• Customer testimonials
• Tutorials
• Course previews
• Landing-page videos
• Feature walkthroughs
• Event recordings
• Company introductions
• Hero video sections

The block supports two playback modes:

• Modal playback
• Inline playback

It can use videos from:

• YouTube
• Vimeo
• Direct MP4 files
• Direct WebM files
• Direct OGG files

Why use a video cover instead of a normal embed?

A standard YouTube or Vimeo embed usually creates its iframe while the page is loading.

Kinetic Video Modal initially renders only the preview image and play button. The provider iframe or native video player is created after the visitor selects Play.

This can reduce:

• Initial third-party requests
• Initial JavaScript work
• Page weight before interaction
• Competition with other page resources
• The number of video players loaded on pages containing several videos

This is particularly useful for video galleries, landing pages, portfolio pages, and documentation pages containing multiple videos.

Add the block

1. Open a page or post in Gutenberg
2. Search for Kinetic Video Modal
3. Insert the block
4. Enter a supported Video URL
5. Choose Modal or Inline playback
6. Add a custom cover or enable YouTube cover extraction
7. Select the aspect ratio
8. Style the play button
9. Configure modal and accessibility settings
10. Update the page
11. Test the video on the frontend

The editor displays a visual preview.

The real video player, modal, playback behavior, and interaction effects run on the frontend.

Required Video URL

The block requires a valid Video URL.

When the URL field is empty:

• The editor displays a warning
• The public frontend does not render the block

The URL should point to a supported provider or directly to a supported video file.

Supported YouTube URLs

Use a normal YouTube URL such as:

https://www.youtube.com/watch?v=VIDEO_ID

or:

https://youtu.be/VIDEO_ID

The block extracts the 11-character YouTube video ID and creates a privacy-enhanced embed using:

youtube-nocookie.com

The generated player also requests:

• Inline playback
• Reduced related-video behavior
• Fullscreen support
• Picture-in-picture support

Use a normal youtube.com or youtu.be URL as the source. KineticHub converts it into the privacy-enhanced player URL automatically.

Supported Vimeo URLs

Use a Vimeo URL containing its numeric video ID, such as:

https://vimeo.com/123456789

The block creates a Vimeo player using the privacy-oriented dnt parameter.

Vimeo URLs using the /video/VIDEO_ID structure are also recognized.

Self-hosted videos

For a local or externally hosted video, enter a direct URL ending in:

• .mp4
• .webm
• .ogg

Example:

To use a file from the WordPress Media Library:

1. Upload the video to Media Library
2. Open the attachment details
3. Copy the File URL
4. Paste it into the Video URL field

The URL must end directly with the supported file extension.

A URL containing additional query parameters after the extension may not be recognized.

For example, this may fail:

video.mp4?version=2

Use a clean direct file URL when possible.

Unsupported URLs

The frontend validates video URLs before creating a player.

Unsupported providers, malformed URLs, and unrecognized file formats are rejected safely.

The block does not create arbitrary iframe embeds from unrestricted domains.

If a video does not open, first test the URL directly in a new browser tab.

Playback Mode

Choose:

• Open in Fullscreen Modal
• Play Inline — Replaces Image

Open in Fullscreen Modal

Opens the video inside a large page-level overlay.

The modal:

• Appears above the existing page
• Locks background page scrolling
• Uses the selected aspect ratio
• Includes a close button
• Supports the Escape key
• Traps keyboard focus while open
• Returns focus to the play button after closing

The term Fullscreen Modal refers to a large viewport overlay. It does not activate the browser’s native Fullscreen API.

Use modal playback when the video should receive the visitor’s complete attention without changing the page layout.

Play Inline — Replaces Image

Replaces the cover preview with the active video player inside the original block.

The inline player:

• Keeps the selected aspect ratio
• Occupies the original preview area
• Hides the cover and play button
• Uses native controls for self-hosted videos
• Starts after the visitor activates Play

The preview remains replaced for the rest of that page view.

There is no separate Restore Cover button in the current inline presentation. Reloading the page restores the initial cover.

Use inline playback for:

• Tutorials
• Product content sections
• Video cards
• Course lessons
• Media placed directly in the page flow

Cover Image

Open Cover Image to configure the visual preview.

The cover is displayed before the actual video player is created.

Custom Cover Image

Select an image from the WordPress Media Library.

A custom cover takes priority over automatic YouTube thumbnail extraction.

Use a custom image when you need:

• Consistent branding
• A specific crop
• Added titles or visual treatment
• Matching thumbnails across several videos
• Better control over image quality

The image fills the complete preview using a cover-style crop.

Alternative text is taken from the selected Media Library image.

Auto-Extract Cover — YouTube

When enabled and no custom cover is selected, KineticHub attempts to retrieve the YouTube thumbnail automatically.

The block first requests:

maxresdefault.jpg

If that image is unavailable, fails to load, remains too small, or does not respond within the fallback period, KineticHub switches to:

hqdefault.jpg

Automatic extraction applies only to recognized YouTube URLs.

For Vimeo and self-hosted video, upload a custom cover image.

When no valid cover is available, the block displays a dark gradient fallback background.

Dark Overlay Opacity

Controls the black overlay displayed above the cover image and below the play button.

Available range:

0–1

Step:

0.1

Default:

0.3

Examples:

• 0 removes the dark overlay
• 0.3 provides a moderate darkening effect
• 0.6 strongly darkens a bright image
• 1 completely covers the image with black

When the visitor hovers over the block, the overlay becomes slightly darker.

Use enough opacity to keep the play button visible, but avoid hiding the cover unnecessarily.

Aspect Ratio

Choose:

• 16:9 — Standard Video
• 4:3 — Classic
• 21:9 — Cinematic
• 1:1 — Square

The selected ratio applies to:

• The preview container
• Inline playback
• Modal content

16:9

Recommended for most YouTube, Vimeo, tutorial, and product videos.

4:3

Useful for archive footage, classic recordings, presentations, and older content.

21:9

Creates a cinematic wide presentation.

Use it when the source video is actually wide enough to avoid excessive empty space or cropping.

1:1

Creates a square player.

Useful for social content, product cards, and square promotional videos.

The square modal is also limited by the available viewport height so it remains visible on smaller screens.

Play Button Design

Open Play Button Design.

Button Style

Choose:

• Solid Color
• Frosted Glass
• Minimal Outline

Solid Color

Displays a filled circular button using the selected Button Background color.

It includes a normal drop shadow for separation from the cover image.

Use it when the play action must be highly visible.

Frosted Glass

Creates a translucent button with:

• Background transparency
• Backdrop blur
• Semi-transparent border
• Soft shadow

The effect is most visible over a detailed cover image.

Browser support for backdrop blur can affect its appearance.

Minimal Outline

Displays a transparent button with a two-pixel colored outline.

In Outline style, the play icon follows the selected Button Background color so the outline and icon remain visually consistent.

Use this style over darker or simpler covers.

Button Size

Controls the diameter of the circular play button.

Available range:

40–150 px

Default:

80 px

Recommended uses:

• 40–60 px for compact cards
• 70–90 px for standard content sections
• 100–150 px for large hero previews

The invisible trigger area surrounding the button is larger than the visible button, making the central interaction easier to activate.

Check large buttons on mobile to make sure they do not cover important parts of the image.

Button Background

Controls:

• Solid button background
• Glass button accent
• Outline border color
• Outline icon color
• Pulse color in PRO

Default:

#10b981

Choose a color with enough contrast against the cover and overlay.

Play Icon Color

Controls the triangular play icon for the Solid and Glass button styles.

Default:

#ffffff

For Minimal Outline, the icon uses the Button Background color to match the outline.

KineticHub PRO playback settings

KineticHub PRO adds:

• Autoplay Video
• Force Loop
• Mute Local/Inline Video
• Start Time

These options are passed to supported provider players and native video elements where applicable.

Autoplay Video — PRO

Enables native autoplay for supported self-hosted modal playback.

YouTube, Vimeo, and inline playback are created after the visitor explicitly selects the play button and are started as user-initiated playback.

Browser autoplay policies can still affect playback, particularly when sound is enabled.

For the most reliable autoplay behavior, combine autoplay with mute.

Force Loop — PRO

Repeats the video after it reaches the end.

The block applies looping differently according to the source:

• YouTube receives loop and playlist parameters
• Vimeo receives its loop parameter
• Self-hosted video receives the native loop property

Use looping for:

• Short product previews
• Ambient demonstration clips
• Repeating animations
• Background-style video content

Avoid forcing long tutorials, testimonials, or full presentations to repeat unnecessarily.

Mute Local/Inline Video — PRO

Controls whether supported playback begins muted.

Although the editor label emphasizes local and inline video, the current frontend also passes the mute preference to supported YouTube and Vimeo players.

The default is enabled.

Mute is recommended when:

• Autoplay is enabled
• Inline playback starts immediately
• The video is decorative
• The page contains several videos
• Unexpected sound would be disruptive

Visitors can use the player controls to change the sound state where the provider or native player permits it.

Start Time — PRO

Starts playback from a selected number of seconds.

Available range:

0–300 seconds

Default:

0

Examples:

• 15 begins at 15 seconds
• 60 begins at one minute
• 120 begins at two minutes

The block applies the start time using:

• YouTube start parameters
• Vimeo time fragments
• Native currentTime after local video metadata loads

The selected time must exist inside the source video.

Image Hover Zoom — PRO

Choose:

• None
• Subtle
• Cinematic — Slow

None

The cover remains at its normal scale.

Subtle

Enlarges the cover to approximately:

1.05

Transition duration:

0.6 seconds

Use it for a restrained interactive response.

Cinematic

Enlarges the cover to approximately:

1.15

Transition duration:

1.5 seconds

Use it for large hero previews and cinematic presentation sections.

The container hides the enlarged image edges so the zoom remains inside the selected ratio.

Teaser Badge Text — PRO

Adds an optional text badge below the play button.

Example labels:

• Watch Trailer
• View Demo
• Product Tour
• Play Reel
• Watch Story

The badge:

• Appears during hover
• Uses uppercase styling
• Sits below the central button
• Is decorative rather than interactive

Keep the label short.

Because touchscreen devices do not provide consistent hover behavior, do not place essential information only inside this badge.

Advanced Interactions — PRO

Magnetic Button Pull

Makes the play button follow the cursor slightly while the pointer moves inside the central trigger area.

The movement uses a fixed pull strength of approximately 30% of the cursor offset with smoothed interpolation.

The button returns to its center position when the pointer leaves.

The effect:

• Runs on mouse interaction
• Does not change the click target
• Does not run when reduced motion is requested
• Does not provide normal desktop-style movement on touchscreens

Use it as a subtle enhancement.

Idle Pulse Animation

Adds an expanding circular pulse around the play button.

The pulse:

• Repeats every two seconds
• Uses the Button Background color
• Expands outward
• Fades as it grows

Use it for one important video rather than every video on a page.

The pulse is disabled when reduced motion is requested.

Modal Settings

The Modal Settings panel appears only when Playback Mode is set to Modal.

Backdrop Style

Choose:

• Dark Glassmorphism
• Light Glassmorphism
• Solid Dark
• Solid Light

Dark Glassmorphism

Uses a semi-transparent dark background with backdrop blur.

This is the default and works well for most videos.

Light Glassmorphism

Uses a semi-transparent light background with backdrop blur.

Use it on light websites where a dark overlay would feel too heavy.

Solid Dark

Uses an almost opaque dark backdrop without relying on glass blur.

This provides strong separation from the page.

Solid Light

Uses an almost opaque light backdrop.

The close button automatically switches to a dark visual treatment for the light backdrop styles.

Modal Entrance Animation

KineticHub Free uses:

• Scale / Zoom

KineticHub PRO adds:

• Slide Up
• 3D Flip
• Fade Only

Scale / Zoom — Free and PRO

The player begins slightly smaller and expands into place while fading in.

Slide Up — PRO

The player enters from below and settles into the center.

3D Flip — PRO

The player enters with a perspective rotation from its lower edge.

Fade Only — PRO

The player appears through opacity without directional or scale movement.

When reduced motion is enabled, modal transitions are removed and the player appears immediately.

Close on Backdrop Click

When enabled, selecting the empty backdrop area closes the modal.

Clicking inside the video container does not close it.

When disabled, visitors must use:

• The close button
• The Escape key

Disable backdrop closing when accidental clicks around the player should not interrupt the video.

Show Close Button Outside

Applies the alternate close-button position used by the modal layout.

Use it when the default top-right button position overlaps important content or provider controls.

The exact visual placement can vary with:

• Aspect ratio
• Modal width
• Viewport dimensions
• Theme CSS

Test the result on desktop and mobile.

Modal dimensions

The modal content uses:

• Approximately 90% of the available viewport width
• A maximum width of 1200 pixels
• A maximum height of approximately 85% of the viewport
• The selected video aspect ratio
• A high overlay stacking level

The page body is temporarily prevented from scrolling while the modal is open.

Closing the modal removes the entire generated player from the page, which also stops its playback.

Local Video Preload

Open A11y & Preload.

Choose:

• Metadata Only — Recommended
• None
• Auto

This setting applies to direct MP4, WebM, and OGG video elements.

It does not control YouTube or Vimeo iframe loading.

Metadata Only

Requests video metadata such as:

• Duration
• Dimensions
• Basic playback information

This is the default.

When a metadata-preloaded native player is created near the viewport, the frontend can upgrade its preload state to Auto.

None

Requests the minimum possible preparation before playback.

Use it when conserving bandwidth is the highest priority.

Auto

Allows the browser to prepare more of the video file.

Use it when:

• The local video is central to the page
• Playback should begin with minimal delay
• The file is appropriately optimized
• Additional bandwidth usage is acceptable

Inline mode creates its native player using Auto preload after the visitor selects Play.

The initial page still renders the cover rather than the complete video player.

Accessibility labels

The block includes three editable labels.

Dialog Aria Label

Default:

Video Player

Describes the modal dialog.

Use a more specific label when possible, such as:

Product demonstration video

or:

Customer testimonial video

Play Button Aria

Default:

Play Video

Describes the central play button.

Recommended examples:

• Play product demo
• Play course introduction
• Watch customer testimonial
• Play company showreel

Close Button Aria

Default:

Close Video

Describes the modal close control.

Use a direct action label such as:

Close product video

Modal keyboard behavior

Modal playback provides:

• Focus moved into the dialog when it opens
• Focus contained inside the open dialog
• Tab and Shift+Tab cycling
• Escape key closing
• Focus restoration after closing
• Visible focus styles
• Screen-reader status announcements

The play button remains a native HTML button and can be activated using normal keyboard controls.

In Modal mode, it also indicates that it opens a dialog.

Screen-reader announcements

When the modal opens, KineticHub announces the configured dialog label followed by an opened state.

When the modal closes, it announces that the video player has closed.

The temporary announcement elements are removed after use.

Video captions and transcripts

Kinetic Video Modal does not generate captions or transcripts.

For YouTube and Vimeo:

• Add and review captions through the video provider
• Avoid relying only on automatically generated captions

For self-hosted video:

• Provide a transcript in the surrounding page content
• Use an appropriately captioned source or another player solution when separate caption-track management is required

Do not communicate essential information only through audio.

Reduced motion

When the visitor requests reduced motion:

• Modal entrance transitions are removed
• Cover zoom transitions are removed
• Play-button transitions are removed
• Idle Pulse is disabled
• Magnetic Button Pull is disabled
• The video and normal controls remain usable

Reduced motion does not automatically prevent video playback.

Visitors still decide whether to activate the player.

WordPress layout controls

Kinetic Video Modal supports:

• Wide alignment
• Full alignment
• Margin
• Padding

The default block width follows its parent content container.

Full alignment depends on theme support.

When the block is displayed as a top-level full-width element, its normal rounded outer corners can be removed so it reaches the page edges cleanly.

The internal video aspect ratio remains active.

Editor and frontend behavior

The Gutenberg editor displays:

• The selected cover
• Fallback cover background
• Overlay opacity
• Button design
• Button size
• Aspect ratio
• PRO badge and visual effects where applicable

The editor does not open the real modal or load the real provider player.

Test the public frontend for:

• Video URL validation
• Provider loading
• Modal entrance
• Inline replacement
• Autoplay
• Looping
• Start time
• Sound state
• Keyboard navigation
• Backdrop closing
• Mobile layout

Performance behavior

The block is designed to avoid loading a complete third-party player during the initial page render.

Before interaction, the page contains:

• The block wrapper
• A cover image or fallback background
• A dark overlay
• A play button

After interaction, the frontend creates:

• A YouTube or Vimeo iframe
• Or a native HTML video element

Additional performance behavior includes:

• Lazy-loaded cover images
• Asynchronous image decoding
• YouTube thumbnail fallback handling
• Loading indicator while provider iframes initialize
• Local video preload control
• Viewport-aware local preload upgrade
• Dynamic initialization for blocks added after page load
• Cleanup of modal players after closing
• Cleanup of magnetic animation when a block is removed

Using several videos on one page

Kinetic Video Modal is suitable for pages containing multiple videos because the provider players are not created initially.

For better results:

• Use optimized cover images
• Use consistent aspect ratios
• Keep local video files compressed
• Avoid unnecessarily large cover dimensions
• Use clear play labels
• Add descriptive headings around each video
• Do not enable strong pulse effects on every item
• Test total page weight on mobile

Each activated modal creates only the player required for that interaction.

Security and URL validation

Before creating a player, the frontend validates the source.

Recognized provider domains include:

• YouTube
• YouTube short links
• YouTube privacy-enhanced domains in the allowlist
• Vimeo

Direct video files must use one of the recognized extensions.

The block does not accept arbitrary iframe HTML from the editor.

Rendered attributes, colors, labels, and URLs are also validated or escaped before output.

Developer hooks

Kinetic Video Modal provides three server-side extension points.

kinetichub_before_video_modal_render

Runs before the block output is generated.

Parameters:

• $attributes
• $block

kinetichub_after_video_modal_render

Runs after the block output is generated.

Parameters:

• $attributes
• $block

kinetichub_video_modal_thumbnail_url

Filters the final generated cover URL.

Parameters:

• $kh_vm_cover_url
• $kh_vm_video_url
• $attributes

Use the thumbnail filter when a project needs a custom thumbnail service or alternative cover-generation rule.

CSS custom properties

The block uses these primary custom properties:

--kh-vm-btn-c

Play button accent color.

--kh-vm-icon-c

Play icon color for supported button styles.

--kh-vm-btn-s

Play button diameter.

--kh-vm-overlay

Cover overlay opacity.

Custom CSS should be scoped to the Video Modal block to avoid interfering with other KineticHub blocks.

Avoid reusing internal .kh-vm-* class names for unrelated custom HTML previews on the same page.

Recommended configurations

Standard YouTube video

• Source: YouTube watch or short URL
• Playback: Modal
• Auto-Extract Cover: Enabled
• Aspect Ratio: 16:9
• Overlay: 0.3
• Button Style: Solid or Glass
• Button Size: 70–90 px
• Backdrop: Dark Glassmorphism
• Close on Backdrop: Enabled
• Specific Play Button Aria label

Product demo

• Custom branded cover
• Playback: Modal
• Aspect Ratio: 16:9
• Button Size: 80–100 px
• Overlay: 0.3–0.5
• Close button positioned away from important content

With PRO:

• Subtle hover zoom
• Magnetic Button Pull
• Teaser Badge: Watch Demo
• Start Time when an introduction should be skipped

Short local video

• Direct optimized MP4 or WebM URL
• Playback: Inline
• Preload: Metadata or Auto
• Custom cover
• Aspect Ratio matching the file
• Mute enabled for immediate playback
• Force Loop only for short repeating clips

Cinematic trailer — PRO

• Playback: Modal
• Custom cover
• Aspect Ratio: 21:9
• Cinematic hover zoom
• Large Outline or Glass button
• Teaser Badge: Watch Trailer
• Dark Glassmorphism backdrop
• Fade or 3D Flip entrance
• Idle Pulse used sparingly

Troubleshooting

The complete block is missing on the frontend

Confirm that Video URL is not empty.

The renderer returns no public output without a URL.

The video does not open

Check:

• The URL opens directly
• The provider is supported
• The YouTube or Vimeo ID is valid
• A local URL ends directly in .mp4, .webm, or .ogg
• No query string follows the local extension
• Frontend JavaScript is loading
• Browser Console does not show an unsupported URL warning

A YouTube URL is rejected

Use a normal:

• youtube.com/watch?v=...
• youtu.be/...

URL.

The block converts it into a privacy-enhanced embed automatically.

The YouTube cover is low resolution

The video may not provide a valid maximum-resolution thumbnail.

KineticHub automatically falls back to the high-quality thumbnail.

Upload a custom cover for complete control.

Vimeo or local video has no automatic cover

Automatic cover extraction currently applies to YouTube.

Upload a custom image for Vimeo and self-hosted video.

The cover is heavily cropped

The cover uses object-fit: cover.

Create an image with the same ratio selected in the block or keep important content near the center.

The button is difficult to see

Adjust:

• Dark Overlay Opacity
• Button Background
• Play Icon Color
• Button Style
• Button Size

Use a stronger overlay when the cover is bright or visually complex.

Icon Color does not change in Outline style

This is expected.

The Outline style uses Button Background as both the border and icon color.

The modal does not close when clicking the background

Confirm that Close on Backdrop Click is enabled.

The click must occur on the backdrop, not inside the video container.

The Escape key does not close the modal

Check whether another script intercepts keyboard events.

Also test without:

• Popup plugins
• Accessibility overlays
• Custom modal scripts
• Page-builder dialogs

The page scrolls behind the modal

Check whether theme CSS overrides the body scroll-lock class.

The modal adds a body class that should set overflow to hidden.

The close button overlaps the video

Try Show Close Button Outside and test the selected ratio.

Also check whether theme CSS overrides .kh-vm-dialog-close.

Inline playback cannot be returned to the cover

This is the current inline behavior.

Reload the page to restore the original preview.

Use Modal playback when visitors should be able to close the player and return immediately to the cover.

Local video does not autoplay

Browser autoplay policies can depend on:

• Sound state
• User interaction
• Browser settings
• Mobile operating system

Enable mute for more reliable automatic playback.

The video begins at the wrong time

Check that Start Time:

• Is expressed in seconds
• Is below the video duration
• Is supported by the provider
• Is tested after clearing caches

Loop does not work on YouTube

YouTube looping requires both loop and playlist parameters.

KineticHub adds both when Force Loop is enabled.

Check that the URL contains a valid recognized YouTube ID.

The modal is blocked by security settings

Review:

• Content Security Policy
• frame-src
• media-src
• Browser privacy extensions
• Cookie or consent systems
• Firewall rules

The site must permit the selected provider and its player domain.

Provider iframe remains on the loading spinner

The player may be blocked by:

• Security headers
• Consent tools
• Ad blockers
• Provider availability
• Network restrictions

Open the browser Console and Network panel to inspect the request.

Magnetic movement does not work

Confirm that:

• KineticHub PRO is active
• Magnetic Button Pull is enabled
• You are testing with a mouse
• Reduced Motion is disabled
• The public frontend is being tested

Pulse does not run

Confirm that:

• KineticHub PRO is active
• Idle Pulse Animation is enabled
• Reduced Motion is disabled
• Custom CSS does not hide the button pseudo-element

Hover zoom does not work on mobile

Touchscreens do not provide normal desktop hover.

The cover remains usable without the zoom effect.

Modal animation appears instantly

The visitor may have reduced motion enabled.

This is the intended accessibility fallback.

Video controls or styling look different

YouTube and Vimeo control their own player interface.

Native MP4, WebM, and OGG controls are rendered by the visitor’s browser.

Their appearance can vary by:

• Browser
• Operating system
• Provider
• Account settings
• Video availability

Next step

This completes the KineticHub Blocks Library.

Return to the Blocks Library overview to review all 12 blocks, or continue with the installation, advanced settings, accessibility, performance, and troubleshooting documentation.