Guide CMS publishing · 8 of 9
How to Embed a Video in WordPress and Check It Works
Embed a YouTube or Vimeo video in WordPress, add context and captions, and check it on the live page with a pass/fail checklist.
Key takeaways
- Paste the URL or use an Embed block for most posts.
- Check captions and add key points as text.
- Test playback and phone fit on the live page.
To embed a video in WordPress, paste the video’s URL into the block editor or add an Embed block, then publish. WordPress turns the link into a player. The step most guides skip is checking it afterward: does it play, does it fit a phone, are captions available, and does the page still read well if the video does not load?
This guide covers how to choose an embed method, add the video, give it context, and check it on the live page. It ends with a pass/fail checklist. For the release steps around it, see the blog publishing guide.
Choose the method
| Method | How it works | Use it when |
|---|---|---|
| Paste the URL | Paste a YouTube or Vimeo link on its own line; WordPress makes an embed | You want the fastest option |
| Embed block | Add a YouTube, Vimeo, or generic Embed block and paste the URL | You want a caption field and block settings |
| Custom HTML | Paste the platform’s embed code in a Custom HTML block | You need player options the block does not offer |
The WordPress Embeds documentation explains that embedding creates a link to content hosted elsewhere. You do not upload the video to your site. The first two methods work for most posts. Use custom HTML only if you need settings such as a start time that the block cannot set, and only with code from the video platform itself.
Embed step by step in the block editor
- Copy the video’s share URL from YouTube or Vimeo.
- In your post, click where the video should go and add a new block.
- Search for “YouTube” or “Vimeo,” or use the general Embed block.
- Paste the URL and click Embed.
- Check the preview player in the editor. If it shows an error, the URL may be private or embedding may be turned off by the owner.
- Add a caption under the player if your theme shows captions.
If your post started in Google Docs, add the video after the text is clean. A pasted video link from a doc may arrive as plain text. The Google Docs to WordPress guide covers that cleanup.
Add context around the embed
A player alone does not tell readers why to watch. Add a short sentence before the video that says what it shows and how long it is. Add a text link to the video below it, so readers can open it directly if the player fails to load.
Use a video only if it adds something your text does not, such as a demonstration. If the video belongs to someone else, follow its platform’s terms. Credit rules for images are covered in the image attribution guide; for embedded video, the platform shows the creator’s name in the player.
Check captions and a transcript or summary
Some readers cannot hear the audio. Others are reading in a quiet place. The W3C explains in its guide to captions and subtitles that captions make audio content available to people who are deaf or hard of hearing.
- Captions: open the video on its platform and check that captions exist and are accurate. Auto-generated captions often need fixes.
- Transcript or summary: for a how-to video, add the key steps as text in the post. The W3C’s transcripts guide explains why a text version helps.
You can only edit captions on a video you own. If it is someone else’s video and it has no captions, consider a different video.
Check it on the live page
An embed can work in the editor and fail on the public page. Scripts, privacy settings, and caching can all affect it. After you publish, or after a scheduled post goes live, open the public URL logged out and check:
- Plays: click play. The video starts without an error.
- Fits mobile: on a phone, the player fits the screen width. Use the mobile review guide for the full phone check.
- No layout jump: the text below does not jump as the player loads. If it does, see how to fix layout shifts caused by images and embeds.
- Start time: if you set one, the video starts at the right point.
- Fallback: the intro sentence and text link make sense even without the player.
Worked example: a how-to post with one video
Fictional example. An imaginary bike repair shop publishes a post on fixing a flat tire, with one embedded YouTube video from its own channel.
| Check | Result | Fix |
|---|---|---|
| Plays on live page | Pass | None |
| Fits phone width | Pass | None |
| Captions available and accurate | Fail: auto captions misspell part names | Edited captions on the channel |
| Steps also in text | Fail: post only said “watch the video” | Added a six-step list under the player |
| No layout jump | Pass | None |
| Text link to video | Pass | None |
Two fixes made the post useful for readers who cannot play the video. The team reran the check, and all items passed.
Privacy and loading
An embedded player loads content from the video platform. That platform may set cookies or collect data when the page loads. Check your site’s privacy policy and any cookie consent rules before you add embeds. Some platforms offer a privacy-enhanced embed option; read the platform’s own help pages for how it works.
Embeds also add weight to a page. One video in a how-to post is usually enough. If you need several, consider linking to a playlist instead of embedding each one.
Who can add embeds
Some embed methods need more access than others. Pasting a URL or using an Embed block works for most roles that can edit posts. Custom HTML may be limited on some sites. The WordPress user roles guide explains how to give each person the access their job needs.
Where DEX fits
DEX publishes approved articles through the connected CMS and checks the live page. Embeds still depend on the video platform, so a person should confirm playback and captions after release.
Post-publish embed checklist
| Check | Pass/fail | Fix if it fails |
|---|---|---|
| Video plays logged out | ☐ | Check privacy and embed settings on the platform |
| Fits a phone screen | ☐ | Use the Embed block instead of fixed-size code |
| Captions exist and are accurate | ☐ | Edit captions, or choose another video |
| Key points also in text | ☐ | Add a summary or step list |
| No layout jump | ☐ | Reserve space for the player |
| Intro sentence and text link present | ☐ | Add them around the player |
FAQ
Do I upload the video to WordPress?
+
No. An embed links to the video hosted on the platform.
Why does my embed work in the editor but not live?
+
Privacy settings, scripts, or caching can affect the public page. Check it logged out.
Do I need captions?
+
They help readers who cannot hear the audio. Check that they exist and are accurate.
Sources
- Embeds · WordPress.org
- Captions/Subtitles · W3C WAI
- Transcripts · W3C WAI
Dex SEO is an AI SEO agent for small businesses. Every article here is planned from search data, drafted by Dex, fact-checked against the sources it cites, and reviewed by the team before it is published.
How this article was made: planned and drafted by Dex from search data, fact-checked by Dex (3 claims checked), then approved by the Dex SEO team.