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. It's commonly used for third-party content like video players, maps, widgets, and external applications.

Vanilla Breeze removes default borders and provides responsive wrapper classes for common aspect ratios, ensuring embedded content scales properly across devices.

When to Use

  • Video embeds - YouTube, Vimeo, and other video platforms
  • Maps - Google Maps, OpenStreetMap embeds
  • Social widgets - Twitter timelines, Facebook posts
  • Payment forms - Stripe, PayPal checkout
  • Third-party tools - Calendars, forms, surveys

When to Use Other Elements

  • Use <video> for self-hosted video files
  • Use <audio> for self-hosted audio
  • Use native components when available instead of embedded widgets

Variants

Default

Basic iframe without borders.

<iframe src="page.html" title="Descriptive title"></iframe>

.bordered

Adds subtle border and rounded corners.

<iframe class="bordered" src="page.html" title="..."></iframe>

.rounded

Medium border radius without border.

.full

Full container width.

.fixed

Full width with fixed height (400px).

Responsive Embeds

Use the .embed-responsive wrapper to maintain aspect ratio while filling available width.

.embed-responsive (16:9 default)

<div class="embed-responsive"> <iframe src="https://www.youtube.com/embed/VIDEO_ID" title="Video title"></iframe> </div>

.ratio-4x3

<div class="embed-responsive ratio-4x3"> <iframe src="..." title="..."></iframe> </div>

.ratio-1x1

.ratio-21x9

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

Security Considerations

Iframes can pose security risks. Follow these best practices:

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

Control which sources can be embedded with the frame-src directive.

<!-- 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

Control what information is sent to the embedded content.

<iframe referrerpolicy="no-referrer" src="..." title="..."> </iframe>

Live Examples

YouTube Video

<div class="embed-responsive"> <iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ" title="YouTube video player" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen> </iframe> </div>

Google Maps

<div class="embed-responsive ratio-4x3"> <iframe src="https://www.google.com/maps/embed?pb=..." title="Map showing office location" loading="lazy" referrerpolicy="no-referrer-when-downgrade"> </iframe> </div>

Vimeo Video

<div class="embed-responsive"> <iframe src="https://player.vimeo.com/video/VIDEO_ID" title="Vimeo video" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen> </iframe> </div>

Accessibility

Title Attribute

Every iframe must have a title attribute that describes its content.

<!-- 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>

Loading Attribute

Defer loading of off-screen iframes for better performance.

<iframe src="..." title="..." loading="lazy"> </iframe>

Best Practices

  • Always provide a descriptive title attribute
  • 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

Related Elements

  • <video> - For self-hosted video content
  • <audio> - For self-hosted audio content
  • <figure> - Wrap embeds that need captions

CSS Reference

Styles defined in /src/native-elements/iframe/styles.css

Selector Properties
iframe display: block; border: none; max-inline-size: 100%;
iframe.full inline-size: 100%;
iframe.fixed 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;