YouTube Embeds
Embed YouTube videos and Shorts in your documentation. Lazy-loaded player, custom start times, and vertical 9:16 Shorts.
The <YouTube> component embeds videos with lazy loading, rounded corners, and no related video clutter. It shows a thumbnail and play button on page load. The full YouTube player loads on click.
Embed a YouTube Video
Pass the video ID as the id prop:
<YouTube id="dQw4w9WgXcQ" />No iframe loads until the viewer clicks play. The component uses lite-youtube-embed: a thumbnail image and a few kilobytes of CSS instead of the 800KB+ YouTube iframe bundle.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | none | Required. The YouTube video ID. |
title | string | "Play" / "YouTube Short" | Accessibility label for the embed. Screen readers use this text. |
start | number | 0 | Start playback at this many seconds into the video. |
short | boolean | false | Render as a vertical 9:16 YouTube Short instead of a 16:9 video. |
Start at a Specific Time
The start prop jumps to a timestamp (in seconds) when playback begins:
<YouTube id="dQw4w9WgXcQ" start={60} />Playback starts at the 1-minute mark. Decimal values are floored to whole seconds.
Finding the Video ID
The video ID is the string after v= in a YouTube URL.
youtube.com/watch?v=dQw4w9WgXcQ→ ID isdQw4w9WgXcQyoutu.be/dQw4w9WgXcQ→ ID isdQw4w9WgXcQ
Copy the ID, not the full URL.
YouTube Shorts
YouTube Shorts are vertical videos with a 9:16 aspect ratio. Embedding a Short in a standard 16:9 player adds thick black bars on both sides.
The short prop fixes this. It renders the embed at 9:16, centered on the page at 360px wide, with rounded corners. The result matches how Shorts look on mobile.
How to Embed a Short
<YouTube id="_6HzLIJPH2A" short />Finding the Short ID
The Short ID is the path segment after /shorts/ in the URL:
youtube.com/shorts/_6HzLIJPH2A→ ID is_6HzLIJPH2A
These IDs follow the same 11-character format as regular YouTube videos. Without short, the <YouTube> component renders a Short in 16:9 with black bars.
Rendering Details
| Detail | How it renders |
|---|---|
| Width | Capped at 360px and centered (matches YouTube's own mobile Shorts player width) |
| Aspect ratio | 9:16 via CSS aspect-ratio, so the container scales cleanly on smaller screens |
| Corners | Rounded with border-radius to stay consistent with other Jamdesk media embeds |
| Related videos | Disabled via rel=0, same as standard embeds |
Performance Difference
Standard YouTube embeds use lite-youtube-embed. It loads no YouTube JavaScript upfront. The page displays a thumbnail image. The full player iframe loads only when a viewer clicks play.
lite-youtube-embed can't render vertical aspect ratios. Shorts use a direct <iframe> with loading="lazy" instead. The browser defers loading until the iframe scrolls near the viewport. The full YouTube player (scripts, styles, and all) initializes when the iframe becomes visible.
One or two Shorts on a page make a negligible difference. Many Shorts add weight from the extra iframes. Link to them or place them behind a tab when a page has more than three or four Shorts. This keeps the initial load lean.
Using iFrames Directly
Use a raw iframe for full control over embed parameters:
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/VIDEO_ID"
title="YouTube video player"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
/>The <YouTube> component is the better default. It lazy-loads the player, strips related videos, and renders Shorts at 9:16. Use raw iframes only when you need embed parameters that the component doesn't expose.