Embed

Code

Copy the markup

import "@luz-ds/catalog/components/embed.css";

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/components/embed.min.css" integrity="sha384-4EY9C7PN373Q38ElCXt3Rp+L44k42GwbC9m/nXfz5dvXn0Zeki8AXTPkFLJU3Qrn" crossorigin="anonymous">

The link is the page without JavaScript, so write it as the page you want a reader to land on: it points to the video where it lives. src is the address of the player, in full, as the other site gives it (here, the privacy-enhanced embed address that YouTube gives for a video); LUZ builds no address and names no provider. The poster is your own image, on your own server: a poster fetched from the other site would reach it on page load.

catalog.min.js loads the element’s own file, embed.min.js, when it scans the page; a page without catalog.min.js loads that file on its own.

<script type="module" src="https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/catalog.min.js"></script>

<luz-embed src="https://www.youtube-nocookie.com/embed/g5aPoRtF2vw?autoplay=1" consent="youtube">
  <a class="luz-embed__link" href="https://www.youtube.com/watch?v=g5aPoRtF2vw">
    <img class="luz-embed__poster" src="/media/apollo-16-poster.jpg" alt="" width="1280" height="720" loading="lazy">
    <span class="u-sr-only">Play video: </span>
    <span class="luz-embed__title">John Young’s Lunar Salute on Apollo 16</span>
  </a>
  <div class="luz-embed__ask" data-luz-embed-ask hidden>
    <p>This video is hosted by YouTube (Google). If you play it, YouTube receives your IP address and details of your browser, and may store information on your device. We receive none of it. <a href="/docs/privacy/">Privacy and storage</a></p>
    <div class="o-actions">
      <button class="luz-btn luz-btn--primary" type="button" value="once">Play this video</button>
      <button class="luz-btn luz-btn--primary" type="button" value="cancel">Do not play</button>
      <button class="luz-btn luz-btn--secondary" type="button" value="always">Always play YouTube videos on this site</button>
    </div>
  </div>
</luz-embed>

Your scripts can ask what the element would load:

import { playerURL } from "@luz-ds/catalog/embed";

// The address the element would load, or null when it stays a link
const url = playerURL(document.querySelector("luz-embed"));

Variants and options

There are no variants. The ratio is a property, and the hooks are attributes.

How it works

CSS from @luz-ds/catalog and a file of its own, @luz-ds/catalog/embed (dist/embed.min.js, under 1.5 kB compressed), which defines <luz-embed>. It uses no library, and the player’s own script, if any, runs only inside the frame, once loaded. A native video or audio does not need it: use the player. This is for what only another site can show.

• Before the click: the page holds a poster and a button, and requests nothing from the other site. When the pointer goes over the button, or focus reaches it, the browser is told to open a connection to the player’s origin (a preconnect, once per origin), unless the site wants consent and it is not granted.
• The click: if nothing needs consent, or it is granted, the frame is written with autoplay permission, and focus goes into it. If consent is needed, the question shows in its place and focus goes to its first button.
• The question: value="once" plays this video. value="always" plays it and stores the category, as the cookie banner does, in localStorage as {"version":1,"expires":…,"asked":[…],"granted":[…],"given":"…"}, merged into the record that is there so the banner’s categories stay, dispatches luz:consent on document and unlocks every other embed with that category. value="cancel" goes back to the poster, with focus on its button. Escape does nothing; the button that cancels is the way back.
• The frame: it has the title of the video, allow for the features players use, allowfullscreen and referrerpolicy="strict-origin-when-cross-origin", which some players need to accept the embed.
• The script writes no text: every word is in your markup, in the page’s language.

A server that builds your pages can write src and save the poster when the content is saved, so a reader never contacts the other site before choosing to.

Without JavaScript

The poster is a link with a visible title that opens the video where it lives, and the question stays hidden. It does the same when src is not valid, and when the category is not granted and there is no question to ask.

Keyboard and ARIA

• Keys: Tab reaches the button; Enter or Space presses it, as on any button. In the question, Tab goes through its buttons. Escape does nothing.
• Name: the button has the name of the link it replaces: the hidden words “Play video:” then the title.
• Focus: to the first button of the question when it shows, into the frame when the player loads, back to the button on Do not play. Once the player is in the frame, its own keys and controls are the other site’s, and the page cannot reach them.
• Language: the question and the names are yours, in the page’s language. The player’s are the other site’s.

Contrast and focus are in the Design tab.

Design

When to use

Use it for a video, a map or any player that a page takes from another site. Loading such a frame sends the reader’s address to that site, and its script weighs more than the rest of the page; a poster and a button cost one image.

When not to use

Do not use it for a video or sound you host: that is the player, which has controls that LUZ styles and a keyboard that LUZ tests.

• Do not use it for a link to a page that happens to have a video: that is a card or a link.
• Do not use it to hide a frame the reader never asked for: it loads only after a click.

It replaces the iframe code that the other site gives you, and the facade scripts for one provider. Nothing in LUZ is removed.

Do and don't

Writing the content

The title is the title of the video, as the reader would say it, and the hidden words before it say what the button does: “Play video:”. Do not repeat the title in the poster’s alt, which stays empty because the title already names it.

• Name the service in the question (“hosted by YouTube (Google)”) and say what it learns (“your IP address and details of your browser”) and what it may do (“store information on your device”), in a few plain sentences, with a link to your privacy page.
• Write the buttons as the action and the thing: “Play this video”, “Do not play”, “Always play YouTube videos on this site”. Give the first two the same weight. Never “OK” or “Yes”.
• Choose a poster whose important part is in the middle: the play mark covers it.

Contrast and focus

The title rides on a scrim that is solid where the text is, so it reads on a white poster too.

Measured from the token values of each mode, rounded down. Needs is the WCAG 2.2 AA minimum: 4.5:1 for text, 3:1 for the play mark, focus rings and edges. The scrim is measured over the page, the lightest poster there is.

• Focus: a 2 px --luz-focus-ring outline around the whole frame, outside it with a 2 px gap, so the poster never hides it. The buttons of the question are core’s.
• The play mark is a disc and a triangle, not colour alone. In forced colors it is a ring and a triangle in the system’s button text.

Tokens it uses

The 14 tokens that the rules of catalog’s components/embed.css read, by family; the buttons of the question are core’s. Each family links to its page, with the values in every mode. In Figma they are variables with the same names: see Tokens in Figma.

Color

--luz-brand-fill, --luz-brand-fill-hover, --luz-focus-ring, --luz-scrim, --luz-surface-media, --luz-surface-muted, --luz-text-on-fill, --luz-text-primary

Spacing and sizing

--luz-space-lg, --luz-space-md, --luz-space-sm

Typography

--luz-font-sans, --luz-text-md

Radius

--luz-radius-md

Keyboard and ARIA are in the Code tab.