Embed

kai-embed

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.

• Shadow DOM
• YouTube · Vimeo · generic
• Privacy-first lazy facade
• Allowlist required for generic origins
• Always-present "Open on provider" fallback

Preview

When to use

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:

<kai-embed id="em"></kai-embed>
<script type="module">
  import '@kitn.ai/ui/elements';
  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)

Code

Vimeo

Code

Generic Player

An allowlisted https URL framed as a generic embed.

Code

Custom Aspect Ratio (9:16)

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

Code

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.

Code

Props

Property	Type	Default	Notes
cardId	string	—	Stable card id correlating every emitted event. Set as an attribute or property.
data	{ … }	—	The embed payload (provider + id/url + options). Set as a JS **property** (object).

Composed from

This element wraps these SolidJS components — reach for them directly when you need finer control than the props expose.

Embed

---

Need a hand? Report a bug Ask for help