# Embed

A privacy-first lazy media embed that renders a poster and play button — no iframe, no third-party JS, no cookies — until the user clicks play.

<p class="kai-tag-sub">kai-embed</p>

Drop a YouTube, Vimeo, or custom player into any generative-UI response — renders a poster and play button first; no provider iframe, scripts, or cookies load until the user clicks play.

## Preview

> **tip:** 
Reach for `<kai-embed>` when an AI response references a video and you want to surface it inline without silently loading third-party scripts. Ideal for YouTube and Vimeo links inside chat messages, cards, or document previews. For arbitrary iframe content use the `generic` provider — but only after allowlisting the origin with `configureEmbedAllowlist`.

## Usage

Set `data` in JavaScript (it's an object, not an attribute) on the element:

```html
<kai-embed id="em"></kai-embed>
<script type="module">

  await customElements.whenDefined('kai-embed');

  const em = document.getElementById('em');
  em.data = { provider: 'youtube', id: 'dQw4w9WgXcQ', title: 'Product intro' };
</script>
```

- **`provider`** — required; `'youtube'`, `'vimeo'`, or `'generic'`. YouTube uses `youtube-nocookie.com`; Vimeo appends `dnt=1`. Neither loads provider JS until play.
- **`generic` embeds are blocked by default** — call `configureEmbedAllowlist(['https://your-player.example.com'])` before setting data. Any unlisted origin is rejected.
- **Vimeo** has no static thumbnail URL — supply a `poster` URL or the facade renders without an image.
- **"Open on provider"** is always visible; on click it fires `kai-card` with `{ kind: 'open', target: 'tab' }` — handle it to open the URL yourself.

## Examples

### YouTube (Lazy)

### Vimeo

### Generic Player

An allowlisted `https` URL framed as a generic embed.

### Custom Aspect Ratio (9:16)

Set `aspectRatio` to `'9:16'` for a vertical short.

### Blocked-Embed Fallback

Some providers block framing via `X-Frame-Options` or CSP. The **"Open on provider"** affordance is always visible, so a blocked embed is never a dead end.

## Props

## Composed from