Tag HTML <iframe>

Il tag <iframe> (abbreviazione di inline frame) incorpora un altro documento HTML all'interno della pagina corrente. È il metodo standard per visualizzare contenuti di terze parti come un lettore video, una mappa, una pubblicità o un widget in sandbox. Il documento incorporato viene caricato in un contesto di navigazione annidato indipendente dalla pagina ospite, ma i due possono interagire tramite JavaScript quando condividono la stessa origine.

Questa pagina tratta la sintassi di <iframe>, i suoi attributi, come dimensionare e stilizzare un frame, il lazy loading nativo del browser, e due funzionalità da usare ogni volta che si incorpora contenuto non completamente controllato: sandbox e allow.

Per incorporare risorse non HTML, consulta anche i tag <embed> e <frame>.

Sintassi

Il tag <iframe> è un normale elemento HTML che richiede un tag di chiusura. Aggiungi sempre un attributo title (vedi Accessibilità più avanti).

Esempio di Tag HTML `<iframe>`

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <iframe src="https://www.w3docs.com" title="W3docs homepage"></iframe>
  </body>
</html>

Provalo tu stesso »

Per impostare le dimensioni dell'iframe, usa gli attributi height e width, oppure utilizza i CSS. I valori degli attributi sono impostati in pixel per impostazione predefinita, ma possono essere anche espressi in percentuale.

Esempio di Tag HTML `<iframe>` con gli Attributi Height e Width

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <iframe src="https://www.w3docs.com" title="W3docs homepage" width="80%" height="300"></iframe>
  </body>
</html>

Provalo tu stesso »

I browser moderni non applicano un bordo predefinito agli iframe. Puoi comunque usare la proprietà CSS border per stilizzare il frame se necessario.

Esempio di Tag HTML `<iframe>` con la Proprietà CSS Border

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <iframe src="https://www.w3docs.com" title="W3docs homepage" width="80%" height="300" style="border: none"></iframe>
  </body>
</html>

Provalo tu stesso »

Incorporare HTML inline con srcdoc

Invece di puntare a un URL con src, puoi fornire l'intero markup del frame inline usando l'attributo srcdoc. Questo è utile per anteprime, snippet in sandbox o HTML generato dove non si dispone di un file o URL separato. Quando entrambi gli attributi sono presenti, srcdoc ha la precedenza (con src usato come fallback per i browser che non supportano srcdoc).

<iframe
  title="Inline greeting"
  srcdoc="<!DOCTYPE html><html><body><h1>Hello from srcdoc!</h1></body></html>">
</iframe>

Poiché il markup si trova in un attributo HTML, le virgolette doppie letterali al suo interno devono essere scritte come " e le e commerciali come &.

Lazy loading degli iframe fuori schermo

L'attributo loading consente al browser di rimandare il caricamento di un iframe finché non è prossimo allo scorrimento nel viewport. Il lazy loading nativo è ora uno standard web stabile, supportato da tutti i browser moderni dal 2020 circa, quindi non è più necessaria una libreria JavaScript per questo caso comune.

Valori supportati:

lazy — rimanda il caricamento finché l'iframe non è vicino al viewport. Consigliato per frame fuori schermo (lettori video, mappe, slot pubblicitari) non visibili al primo rendering.
eager — carica la risorsa immediatamente, indipendentemente dalla sua posizione. Questo è il valore predefinito.

<iframe src="video-player.html" title="Promo video" loading="lazy"></iframe>

Rimandare gli iframe fuori schermo riduce il peso iniziale della pagina, accelera il primo caricamento ed evita di sprecare la banda dell'utente su contenuti che potrebbe non scorrere mai.

Limitare i contenuti con l'attributo sandbox

Per impostazione predefinita, una pagina incorporata può eseguire script, inviare moduli, aprire popup, navigare nella pagina di primo livello e leggere i cookie della propria origine. Quando si incorpora contenuto non completamente controllato, questo rappresenta un rischio per la sicurezza. L'attributo sandbox applica un insieme rigoroso di restrizioni, permettendo poi di riabilitare solo le funzionalità effettivamente necessarie al frame elencando token separati da spazi.

Un sandbox vuoto (cioè sandbox="") applica tutte le restrizioni: nessuno script, nessun modulo, nessun popup, nessun plugin, e il contenuto è forzato in un'origine opaca univoca. Puoi poi allentarlo token per token:

Token	Riabilita
`allow-forms`	Invio di moduli.
`allow-same-origin`	Trattare il contenuto come stesso-origine (in modo che possa usare i propri cookie e storage).
`allow-scripts`	Esecuzione di JavaScript.
`allow-popups`	Apertura di nuove finestre o schede (es. `window.open`, `target="_blank"`).
`allow-downloads`	Avvio di download di file.
`allow-modals`	Visualizzazione di finestre di dialogo modali come `alert()`, `confirm()` e `prompt()`.
`allow-top-navigation`	Navigazione nel contesto di navigazione di primo livello (la pagina padre).
`allow-pointer-lock`	Utilizzo dell'API Pointer Lock.

Combina allow-scripts e allow-same-origin con attenzione: concedere entrambi a contenuti provenienti da un'altra origine consente effettivamente a quel contenuto di rimuovere la propria sandbox, quindi fallo solo per contenuti di cui ti fidi.

Esempio di `<iframe>` con Sandbox

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <iframe
      src="https://example.com/widget.html"
      title="Third-party widget"
      sandbox="allow-scripts allow-forms">
    </iframe>
  </body>
</html>

Qui il widget può eseguire script e inviare moduli, ma non può navigare nella pagina padre, aprire popup, né accedere ai cookie e allo storage della stessa origine.

Consentire funzionalità del browser con l'attributo allow

Mentre sandbox controlla le restrizioni di base del contesto di navigazione, l'attributo allow imposta una Permissions Policy per il frame — stabilisce quali potenti funzionalità del browser (fotocamera, microfono, geolocalizzazione, schermo intero, autoplay, ecc.) il documento incorporato può utilizzare. La maggior parte di queste funzionalità è bloccata negli iframe cross-origin a meno che non si opti con allow.

<iframe
  src="https://example.com/player.html"
  title="Video player"
  allow="fullscreen; camera 'none'">
</iframe>

Questo concede al frame il permesso di entrare in modalità schermo intero negando esplicitamente l'accesso alla fotocamera. È possibile limitare una funzionalità a origini specifiche, ad es. allow="geolocation 'self' https://maps.example.com".

Accessibilità

Ogni <iframe> dovrebbe avere un attributo title che descriva brevemente lo scopo del frame. I lettori di schermo annunciano il titolo affinché gli utenti capiscano di cosa tratta il contenuto incorporato prima di entrarvi; senza un titolo, il frame viene annunciato solo come un "frame" senza etichetta, il che crea confusione.

<iframe src="map.html" title="Map showing our office location"></iframe>

Usa un titolo conciso e univoco per ogni iframe nella pagina (ad esempio "Sondaggio di feedback dei clienti" anziché semplicemente "iframe").

Quando una pagina rifiuta di essere incorporata in un frame

L'incorporamento non sempre riesce: la pagina a cui punta src può rifiutarsi di essere visualizzata all'interno di un frame. I siti lo fanno per prevenire il clickjacking, in cui un aggressore sovrappone un frame nascosto alla propria interfaccia utente. Una pagina può rifiutare di essere inquadrata in due modi:

L'header HTTP di risposta legacy X-Frame-Options (DENY o SAMEORIGIN).
La moderna direttiva frame-ancestors della Content-Security-Policy, ad es. Content-Security-Policy: frame-ancestors 'self'.

Se un sito di destinazione invia uno di questi, il tuo iframe mostrerà un frame vuoto o di errore invece del contenuto — questo è il comportamento previsto, non un bug nel tuo markup. Molti siti di grandi dimensioni (banche, social network) bloccano l'incorporamento per motivi di sicurezza, motivo per cui non è possibile incorporarli direttamente.

Attributi

Attributo	Valore	Descrizione
align	left right top bottom middle	Specifica come il testo è allineato e disposto attorno al frame. Non supportato in HTML5.
allow	string	Specifica una policy che consente o limita determinate funzionalità nell'iframe.
allowfullscreen		Definisce che il frame può essere aperto in modalità schermo intero.
frameborder	1 0	Definisce se il bordo dell'iframe attorno al frame deve essere visualizzato o meno. Non supportato in HTML5.
height	pixels	Definisce l'altezza del frame (altezza predefinita 150px).
longdesc	URL	Definisce una pagina con una descrizione lunga del contenuto. Non supportato in HTML5.
marginheight	pixels	Definisce i margini superiore e inferiore del frame. Non supportato in HTML5.
marginwidth	pixels	Definisce i margini sinistro e destro del frame. Non supportato in HTML5.
loading	eager lazy	Imposta se il frame viene caricato immediatamente o rimandato finché non è vicino al viewport.
name	text	Definisce il nome del frame (una destinazione per link e moduli).
referrerpolicy	keyword	Imposta quali informazioni del referrer inviare con la richiesta. Accetta una keyword come `no-referrer`, `origin` o `strict-origin-when-cross-origin` — non un URL.
sandbox	token list	Applica restrizioni aggiuntive al contenuto del frame. Vuoto (`sandbox=""`) applica tutte le restrizioni; aggiungi token separati da spazi come `allow-scripts` o `allow-forms` per allentarle. Vedi la sezione sandbox.
scrolling	yes no auto	Definisce se la barra di scorrimento deve essere visualizzata o meno. Non supportato in HTML5.
seamless	seamless	Specifica che il contenuto del documento allegato deve essere visualizzato come parte del documento padre.
src	URL	Specifica l'indirizzo del documento il cui contenuto verrà caricato nel frame.
srcdoc	HTML code	Memorizza il contenuto del frame direttamente nell'attributo, invece di caricare un URL separato.
title	text	Descrive il contenuto del frame per le tecnologie assistive. Dovrebbe essere presente in ogni iframe.
width	pixels	Definisce la larghezza del frame. (larghezza predefinita 300px).

Il tag <iframe> supporta gli attributi globali e gli attributi evento.

Tag correlati

Tag HTML <frame> — definisce un singolo frame all'interno di un <frameset> (frameset legacy, obsoleto in HTML5).
Tag HTML <embed> — incorpora contenuti esterni come un plugin o una risorsa multimediale.

Esercitazione

Pratica

Quale attributo dovrebbe essere presente in ogni iframe affinché i lettori di schermo possano annunciarne lo scopo?

title: Descrive il contenuto del frame per le tecnologie assistive.name: Imposta il nome dell'iframe.align: Un attributo HTML5 obsoleto che posizionava il frame a sinistra o a destra.src: Specifica l'URL del documento da incorporare.

Sintassi

Esempio di Tag HTML <iframe>

Esempio di Tag HTML <iframe> con gli Attributi Height e Width

Esempio di Tag HTML <iframe> con la Proprietà CSS Border

Incorporare HTML inline con srcdoc

Lazy loading degli iframe fuori schermo

Limitare i contenuti con l'attributo sandbox

Esempio di <iframe> con Sandbox

Consentire funzionalità del browser con l'attributo allow

Accessibilità

Quando una pagina rifiuta di essere incorporata in un frame

Attributi

Tag correlati

Esercitazione

Esempio di Tag HTML `<iframe>`

Esempio di Tag HTML `<iframe>` con gli Attributi Height e Width

Esempio di Tag HTML `<iframe>` con la Proprietà CSS Border

Esempio di `<iframe>` con Sandbox