branded-thumb

npm: @playerstack/plugin-branded-thumb

Renders a custom poster overlay with an accessible play button. Optional clickToLoad mode defers the underlying iframe until the user clicks — eliminating third-party cookies and dramatically improving Largest Contentful Paint.

Quickstart

<player-stack
  src="https://youtu.be/dQw4w9WgXcQ"
  poster="https://cdn.example.com/poster.webp"
  data-config='{"brandedThumb":{"enabled":true,"clickToLoad":true,"playButtonStyle":"box"}}'
>
</player-stack>

Config

config.brandedThumb:

Field	Type	Default	Description
`enabled`	boolean	`false`	Plugin is a no-op unless `true`
`playButtonStyle`	`"minimal" \| "box" \| "circle"`	`"circle"`	Visual style of the play button (CSS hook via `data-style`)
`clickToLoad`	boolean	`false`	Defer iframe load until click (LCP + GDPR)

Why clickToLoad

YouTube and Vimeo iframes fetch tracking cookies as soon as they load — even before the user plays anything. With clickToLoad: true:

No third-party cookies until the user clicks. You don’t need a GDPR consent prompt for the embed itself.
Better Largest Contentful Paint — about 200 KB of YouTube/Vimeo JS is deferred.
Cleaner privacy story — perfect for compliance-focused brands.

The trade-off: the user has to click twice (once to load, once to play). For most use cases that’s acceptable.

How it works

When clickToLoad: true:

The sources plugin sees the flag and skips setting src on the inner media element, so the YouTube/Vimeo iframe (or the <video> request) is never made
The plugin mounts an overlay with the poster and play button
On click, the plugin sets the src attribute (the inner element loads), calls play() synchronously to preserve the user-gesture for autoplay policy, removes the overlay, and emits thumb:click

Events

Name	Payload	When
`thumb:click`	`undefined`	User clicks the overlay

Track it via the event bus:

ctx.events.on("thumb:click", () => {
  // analytics / consent prompt / etc.
});