Video poster attribute: the frame shown before playback

What the poster attribute is

poster on a <video> element names an image the browser shows in the video’s box until playback starts. Without it, the browser shows either nothing or the first frame, and the first frame of most videos is black.

It is a perceived-performance measure as much as a design one. The poster is a normal image, so it loads at image speed and gives the reader something to look at while the video is still buffering. An embedded player has no poster: its preview frame is configured through the provider. thumbnailUrl in the VideoObject schema is a separate thing, the image a search result uses, not the one the embed renders.

What squirrel checks

The rule runs on every crawled page over every <video> element and checks for a poster attribute. It emits a single check named video-thumbnail:

• Info when the page has no <video> element. Message: No HTML5 video elements found.
• Warn when any video has no poster. Message: 2 video(s) missing poster attribute, with Add poster images for better UX as the value.
• Pass otherwise. Message: All 3 video(s) have poster images.

Only the presence of the attribute is checked. The image is not fetched, so a poster pointing at a 404 passes. Severity info, weight 3.

How to fix it

<video controls poster="/talk-poster.jpg" width="1280" height="720">
  <source src="/talk.mp4" type="video/mp4" />
</video>

Use a frame from the video itself at 1280 by 720 or larger, and give the element width and height so the box is reserved before the poster loads.

For an embedded video, set the preview through the player or provider, and supply thumbnailUrl on the VideoObject node separately for search.

Enable / disable

Disable this rule

[rules]
disable = ["video/video-thumbnail"]

Disable all Video rules

[rules]
disable = ["video/*"]

Enable only this rule

[rules]
enable = ["video/video-thumbnail"]

enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.

Related rules

• video/video-schema: the thumbnailUrl the schema needs for an embed.
• video/video-accessible: captions on the same element.
• images/dimensions: width and height attributes that reserve space for images.
• perf/lcp-hints: likely LCP images that lack a preload.

Video findings ship in every audit next to the SEO, performance and agent experience rules. See Fix SEO issues with AI for how an agent works through a report.

References

• The video element, MDN
• Video best practices, Google Search Central

Check your site

Run squirrel audit https://example.com and open the Video section of the report. Each page is reported with how many of its videos carry a poster. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.