Video Block

The Video block allows you to upload or embed video directly into your page or post. It’s a native WordPress block designed to support simple video playback within your content.

Why use the Video block

Important: Most sites should use externally hosted video platforms like YouTube or Vimeo for better performance, accessibility, and reliability. Uploading videos to the Media Library should be avoided whenever possible and used only in limited cases. While the Video block supports both approaches, choosing the right one has a direct impact on site performance and user experience.

Use the Video block when you want to include video content as part of your page experience.

It’s commonly used for:

  • Embedding hosted videos from platforms like YouTube or Vimeo
  • Adding product demos, tutorials, or recorded presentations
  • Supporting written content with visual or motion-based media
  • Providing richer storytelling or instructional content

How to use the block

Start by adding the Video block to the page. Learn how to add blocks.

When the block is added, you’ll be prompted to choose how to add your video:

  • Upload: Upload a new video file from your computer
  • Media Library: Select a video already uploaded to your site
  • Insert from URL: Paste a video link
  • If you paste a URL from a supported platform (like YouTube or Vimeo), the block will automatically convert into the appropriate Embed block.

Once the video is added, what you can do next depends on how the video is being used:

If you’re using an uploaded video (Upload or Media Library):

  • Configure playback and behavior settings
  • Add captions or accessibility features (like text tracks)
  • Adjust layout and spacing to fit the page

If you’re embedding a video from an external platform (like YouTube or Vimeo):

  • The block will convert into an Embed block with its own settings
  • Playback behavior and controls are managed by the video platform
  • You can still adjust layout and spacing within the page

Block toolbar

The block toolbar appears above the Video block when it’s selected.

Available options

  • Add caption: Add a visible caption below the video. Use this to provide context or attribution
  • Block width: Control how wide the video appears within the layout
  • Text tracks: Upload a .vtt file for captions, subtitles, or descriptions. This helps improve accessibility and usability
  • Replace: Swap the video file or URL with a different source

Block settings

Block settings appear in the right sidebar while the block is selected.

Playback settings

Control how the video behaves when viewed.

  • Autoplay: Starts playback automatically when the page loads
  • Loop: Replays the video continuously
  • Muted: Mutes audio by default
  • Playback controls: Shows or hides player controls (play, pause, volume, etc.)
  • Play inline: Keeps playback within the page on mobile devices instead of full screen

Loading behavior

  • Preload: Controls how much of the video loads when the page loads
  • Auto: Loads the full video
  • Metadata: Loads basic information only
  • None: Does not preload video data

Poster image

  • Upload a custom image to display before the video plays
  • Acts as a thumbnail and improves perceived load time

Block styles

In the Styles tab of the block settings sidebar, you can adjust layout spacing.

Dimensions

  • Margin: Controls space around the video
  • Padding: Controls space inside the video container

Accessibility

How accessibility is handled depends on how the video is added:

If you’re using an uploaded video (Media Library):

  • Add text tracks (captions or subtitles) using .vtt files
  • Include a caption when context or explanation is needed
  • Avoid autoplay when possible — especially with sound
  • Ensure controls are available so users can pause or adjust playback

If you’re embedding from an external platform (like YouTube or Vimeo):

  • Captions, controls, and playback behavior are managed by the video platform
  • Ensure captions or subtitles are configured on the platform itself
  • Avoid autoplay with sound, as it can create accessibility and usability issues

Captions and playback controls make video content usable for a much wider audience, including people using screen readers and those with hearing impairments.

Tips for editors

Prefer external hosting

Uploading videos directly to the Media Library can slow down your site and impact performance. Whenever possible, use platforms like YouTube or Vimeo and embed via URL.

If uploading, optimize aggressively

If you must upload a video to the Media Library:

  • Use MP4 (H.264 video, AAC audio) for best compatibility
  • Optionally provide WebM as a secondary format
  • Keep file sizes between 2–10 MB
  • Limit resolution to 1080p or lower (720p is often sufficient)

Improve page performance

  • Set Preload to None or Metadata to prevent large downloads on page load
  • Add a Poster image so the video doesn’t appear blank while loading

Be intentional with autoplay

If using autoplay:

  • Enable Muted (required for most browsers)
  • Use sparingly to avoid distracting users

Support mobile playback

Enable Play inline so videos stay within the page on mobile devices instead of forcing full-screen playback.

Keep media library files organized and searchable

When uploading videos to the Media Library, use clear, descriptive file names. Well-named files improve searchability in the dashboard and make ongoing content management much easier.

  • Rename files before uploading (e.g., product-demo-2024.mp4)
  • Use consistent naming patterns to make files easier to find later
  1. WordPress.org Video block documentation – Please note that your implementation may include customizations that affect available settings or behavior.