Steve Grunwell

Open-source contributor, speaker, and electronics tinkerer

Automatically Set a Poster Image for WordPress Video Embeds

I’m working on a client project right now that makes heavy use of embedded videos. It’s exciting because as someone who primarily develops themes and plugins for marketing sites (and whose personal blog is almost exclusively text and code) it’s rare that I really spend much time with the rich-media embeds that have been getting so much attention from the core team over the last few releases.

As I started playing with the video embeds I immediately noticed an issue – there was nothing in the media widget that allowed authors to set a poster frame (the static image that appears in the video player before the user clicks the play button). I checked the documentation for the video shortcode and found that the shortcode accepts an optional poster attribute, which allows authors to specify a poster image.

The site I’m working on could be classified a video news blog; each post contains a single video and some supporting textual content. The theme makes use of featured images (post thumbnails), which seems like a natural place to set the poster frame. To avoid authors having to manually set the poster attribute on every video embed I whipped up the following snippet:

This snippet overrides the default “video” shortcode (which normally just calls wp_video_shortcode()) so that we can inject the post thumbnail as a poster frame if the attribute hasn’t already been set. If you wanted to take it a step further you could very easily do things like set default poster frames, change behavior based on post format (for instance, only do this on video posts), etc.


Gravity Forms Duplicate Prevention


Laravel Application Environments without Hostnames


  1. Luke Clifton

    Thanks Steve. This post help me out…just the info i was needing.

  2. anil


  3. Thanks Steve, this functions is useful today!

  4. COOOL…sick tip, dude – just what I was looking for and worked like a charm!

  5. Hey dude – how would I get around the fact that ALL of my thumbnails are 16:9, but some of my videos are strange resolutions? The posters work, they just tile (vertically, generally, as some of my movies are more SD than anything).

    Is it possible to center the poster and expand it to fill 100% of the height or width, whichever comes last?

    Either way, still a great and useful tip!

    • I’m not sure if there’s a native way to specify how poster frames should be positioned/sized, but you could use the wp_video_shortcode filter to alter the output and fake the desired effect (perhaps using pseudo-elements with background images and background-size: cover;?)

      If you find a more native way to do it, I’d love to hear it!

  6. Renan

    Where a put this code? I can’t find this line “wp_video_shortcode.


    • wp_video_shortcode is an internal WordPress function that you’ll be calling from within your theme. The block of code in this post would be added into your theme’s functions.php file.

  7. This is nice, Mr. Grunwell. I wish WordPress would enable poster image as a feature for external embeds (like from S3). Question about something you said…”we can inject the post thumbnail as a poster image if the attribute hasn’t already been set”: To your knowledge, can we set a poster image in a straight up embed for an external url? E.g. something like this?

  8. Steve

    how about iframe video .. like mixdrop, gounlimited.
    How to call the short code for iframe..
    new to this stuff, Kindly help

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Be excellent to each other.