Components

YouTube Embed (Optimized)

Performance-first <ws-youtube> embed: poster first, then iframe or IFrame API only when needed. Behaviour splits on autoplay, mobile/Safari, optional js-api, and params for YouTube chrome.

Jump to:

Download & setup

Download WCKD UI Style guide

Start with the package download and setup steps in Get Started, then use the style guide for utility and token references while implementing this component.

Default implementation

Default: click to load

Set videoid and title (title drives the poster overlay via data-title). First user click loads the embed once. On many desktops this uses a lightweight nocookie iframe; on mobile, Safari, or when you add js-api, the IFrame API path is used instead.

Markup

<ws-youtube videoid="VIDEO_ID" title="Accessible video title"></ws-youtube>

Configuration options

Start from the default implementation, then apply one of these intent-driven variations based on your content and interaction goals.

Player chrome: params

Pass YouTube embed query parameters via params (merged into the embed URL / playerVars). Example: modest branding and limit related videos. See YouTube IFrame Player parameter reference for the full list.

Markup

<ws-youtube videoid="VIDEO_ID" title="Title" params="modestbranding=1&rel=0"></ws-youtube>

Hide controls: controls=0

With params containing controls=0, core CSS sets pointer-events: none on the iframe so the clip reads as non-interactive chromeless. Use for decorative loops where you do not want scrubbing; pair with your own CTA or page chrome if users need actions.

Markup

<ws-youtube videoid="VIDEO_ID" title="Ambient" params="controls=0&modestbranding=1"></ws-youtube>

Autoplay in view

Add autoplay (omit or set to anything other than false). Initialisation uses an IntersectionObserver at ~10% visibility: enters viewport → load and play, leaves → pause. Autoplay path uses the IFrame API and starts muted where required (muted attribute also forces mute in the player-ready handler).

Markup

<ws-youtube videoid="VIDEO_ID" title="Hero" autoplay muted></ws-youtube>

Hero banner background video (autoplay)

Demonstration only: the same hero .background-video slot as native <video>, with <ws-youtube> instead. Not recommended for production decorative backgrounds. YouTube runs in a cross-origin iframe, so your CSS cannot style how the stream is framed inside the player the way <video> plus object-fit: cover can. If the iframe is taller or wider than 16:9, the player typically letterboxes the video inside the iframe (bars you cannot remove from the parent page). Prefer self-hosted muted <video> for predictable full-bleed motion, lighter pages, and simpler autoplay behaviour.

YouTube

Video

Use the standard hero .background-video pattern and swap native <video> for <ws-youtube>

Get Started Browse components

Markup

<section class="height-75">
  <div class="background-video opacity-1">
    <ws-youtube
      videoid="VIDEO_ID"
      title="Hero background video"
      autoplay
      muted
      params="autoplay=1&mute=1&controls=0&rel=0&modestbranding=1&loop=1"
    ></ws-youtube>
  </div>

  <div class="overlay tint-light">
    <div class="pad-xl width-l align-center align-middle center">
      <!-- Hero headline / CTA -->
    </div>
  </div>
</section>

Playback ownership (one active player)

Playback control is separate from viewport autoplay: when one ws-youtube starts, other ws-youtube instances on the page are paused automatically.

Markup

<div class="columns count-2 gap-s">
  <div class="column"><ws-youtube videoid="VIDEO_ID_A" title="Player A"></ws-youtube></div>
  <div class="column"><ws-youtube videoid="VIDEO_ID_B" title="Player B"></ws-youtube></div>
</div>

When to use

  • Use default click-to-load for marketing pages and docs where most visitors never play.
  • Use params to tune branding, related videos, start time, and controls visibility.
  • Use autoplay only when in-view motion is intentional and muted autoplay is acceptable.

Implementation notes

  • Always set title for accessibility; it is mirrored to data-title for the poster overlay.
  • params is a query string: values merge with internal defaults (playsinline, enablejsapi when needed, autoplay flags on activation).
  • Poster uses YouTube thumbnails; you can set style="background-image: url(...)" on the host before upgrade if you need a custom still.
  • A noscript fallback is injected automatically for progressive enhancement.

Developer checklist

  • Confirm videoid matches the public YouTube ID only (no full URL).
  • Test one embed on mobile Safari and one with autoplay to verify the API vs basic iframe path.
  • If using controls=0, validate that pointer-events: none on the iframe matches the product expectation.

← All components