iframe
The iframe element embeds external content with responsive containers and security best practices for third-party integrations.
Description
The <iframe> element embeds another HTML document within the current page. VB removes default borders, provides variant classes for visual style, and offers responsive wrapper classes for common aspect ratios.
When to Use
- Video embeds: YouTube, Vimeo, and other video platforms
- Maps: Google Maps, OpenStreetMap embeds
- Social widgets: Twitter timelines, social posts
- Payment forms: Stripe, PayPal checkout
- Third-party tools: Calendars, forms, surveys
When to Use Other Elements
Variants
VB removes the default iframe border and provides variant classes for visual style.
<iframe src="page.html" title="Descriptive title"></iframe><iframe class="bordered" src="page.html" title="..."></iframe>| Class | Effect |
|---|---|
| (default) | No border, block display, max-width 100% |
.bordered | Subtle border with rounded corners |
.rounded | Medium border radius, overflow hidden |
.full | 100% container width |
.fixed | 100% width, fixed 400px height |
Responsive Embeds
Wrap an iframe in an .embed-responsive container to maintain aspect ratio while filling available width. The iframe stretches to fill the container via absolute positioning.
<section class="embed-responsive"> <iframe src="https://www.youtube-nocookie.com/embed/VIDEO_ID" title="Video title" allowfullscreen> </iframe></section><section class="embed-responsive ratio-4x3"> <iframe src="..." title="..."></iframe></section>| Wrapper Class | Aspect Ratio | Use Case |
|---|---|---|
.embed-responsive | 16:9 | YouTube, Vimeo, most video |
.ratio-4x3 | 4:3 | Classic presentations, some maps |
.ratio-1x1 | 1:1 | Instagram embeds, square widgets |
.ratio-21x9 | 21:9 | Cinematic video, ultrawide content |
Live Embeds
Real-world embed examples showing YouTube video and OpenStreetMap.
<section class="embed-responsive"> <iframe src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ" title="YouTube video player" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen loading="lazy"> </iframe></section><section class="embed-responsive ratio-4x3"> <iframe src="https://www.openstreetmap.org/export/embed.html?bbox=..." title="Map showing office location" loading="lazy"> </iframe></section>Privacy note: Use youtube-nocookie.com instead of youtube.com for privacy-enhanced mode that doesn't set tracking cookies until the user plays the video.
Security
The sandbox Attribute
Restricts iframe capabilities. Start with an empty value (most restrictive) and add permissions as needed.
<!-- Most restrictive: no scripts, forms, or same-origin access --><iframe sandbox src="..." title="..."></iframe> <!-- Allow scripts only --><iframe sandbox="allow-scripts" src="..." title="..."></iframe> <!-- Common for video embeds --><iframe sandbox="allow-scripts allow-same-origin" src="..." title="..."></iframe> <!-- For forms --><iframe sandbox="allow-forms allow-scripts allow-same-origin" src="..." title="..."></iframe>| Sandbox Value | Allows |
|---|---|
allow-scripts | JavaScript execution |
allow-same-origin | Treat content as same origin |
allow-forms | Form submission |
allow-popups | Open new windows/tabs |
allow-modals | Modal dialogs (alert, confirm) |
allow-downloads | Downloading files |
Content Security Policy
<!-- HTTP header -->Content-Security-Policy: frame-src 'self' https://www.youtube.com https://player.vimeo.com; <!-- Meta tag --><meta http-equiv="Content-Security-Policy" content="frame-src 'self' https://www.youtube.com;">Referrer Policy
<iframe referrerpolicy="no-referrer" src="..." title="..."></iframe>Accessibility
Title Attribute
Every iframe must have a title attribute that describes its content for screen readers.
<!-- Good: descriptive title --><iframe src="https://www.youtube.com/embed/..." title="Introduction to Web Accessibility - Tutorial Video"></iframe> <!-- Bad: generic or missing title --><iframe src="..."></iframe><iframe src="..." title="iframe"></iframe>Lazy Loading
Defer loading of below-the-fold iframes for better performance.
<iframe src="..." title="..." loading="lazy"></iframe>Best Practices
- Always provide a descriptive
titleattribute - Use
loading="lazy"for below-the-fold embeds - Ensure embedded content is itself accessible
- Provide alternative content for critical information
- Consider that some users block third-party content
CSS Reference
| Selector | Properties |
|---|---|
iframe | display: block; border: none; max-inline-size: 100%; |
iframe.full | inline-size: 100%; |
iframe.fixed | inline-size: 100%; block-size: 400px; |
iframe.rounded | border-radius: var(--radius-m); overflow: hidden; |
iframe.bordered | border; border-radius; |
.embed-responsive | position: relative; aspect-ratio: 16 / 9; |
.embed-responsive > iframe | position: absolute; inset: 0; 100% width/height; |