Balise HTML <iframe>

La balise <iframe> (abréviation de inline frame, cadre en ligne) intègre un autre document HTML à l'intérieur de la page courante. C'est la méthode standard pour afficher du contenu tiers tel qu'un lecteur vidéo, une carte, une publicité ou un widget sandboxé. Le document intégré est chargé dans un contexte de navigation imbriqué indépendant de la page hôte, mais les deux peuvent interagir via JavaScript lorsqu'ils partagent la même origine.

Cette page couvre la syntaxe de <iframe>, ses attributs, comment dimensionner et styliser un cadre, le chargement différé natif du navigateur, ainsi que les deux fonctionnalités à utiliser systématiquement lorsque vous intégrez du contenu que vous ne contrôlez pas totalement : sandbox et allow.

Pour intégrer des ressources non-HTML, consultez également les balises <embed> et <frame>.

Syntaxe

La balise <iframe> est un élément HTML ordinaire qui nécessite une balise de fermeture. Ajoutez toujours un attribut title (voir Accessibilité ci-dessous).

Exemple de balise 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>

Essayez vous-même »

Pour définir la taille d'une iframe, utilisez les attributs height et width, ou utilisez CSS. Les valeurs des attributs sont définies en pixels par défaut, mais elles peuvent aussi être exprimées en pourcentage.

Exemple de balise HTML `<iframe>` avec les attributs Height et 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>

Essayez vous-même »

Les navigateurs modernes n'appliquent pas de bordure par défaut aux iframes. Vous pouvez tout de même utiliser la propriété CSS border pour styliser le cadre si nécessaire.

Exemple de balise HTML `<iframe>` avec la propriété 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>

Essayez vous-même »

Intégrer du HTML en ligne avec srcdoc

Au lieu de pointer vers une URL avec src, vous pouvez fournir l'intégralité du balisage du cadre directement en ligne grâce à l'attribut srcdoc. C'est pratique pour les aperçus, les extraits sandboxés ou le HTML généré lorsque vous n'avez pas de fichier ou d'URL séparé. Lorsque les deux attributs sont présents, srcdoc a la priorité (src servant de solution de repli pour les navigateurs qui ne prennent pas en charge srcdoc).

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

Comme le balisage se trouve dans un attribut HTML, les guillemets doubles littéraux à l'intérieur doivent être écrits sous la forme " et les esperluettes sous la forme &.

Chargement différé des iframes hors écran

L'attribut loading permet au navigateur de différer le chargement d'une iframe jusqu'à ce qu'elle soit sur le point d'apparaître dans la zone visible. Le chargement différé natif est désormais une norme web stable, prise en charge par tous les navigateurs modernes depuis environ 2020, de sorte que vous n'avez plus besoin d'une bibliothèque JavaScript pour ce cas courant.

Valeurs prises en charge :

lazy — diffère le chargement jusqu'à ce que l'iframe soit proche du viewport. Recommandé pour les cadres hors écran (lecteurs vidéo, cartes, emplacements publicitaires) qui ne sont pas visibles lors du premier rendu.
eager — charge la ressource immédiatement, quelle que soit sa position. C'est la valeur par défaut.

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

Différer les iframes hors écran réduit le poids initial de la page, accélère le premier chargement et évite de consommer la bande passante de l'utilisateur sur du contenu vers lequel il ne fera peut-être jamais défiler.

Restreindre le contenu avec l'attribut sandbox

Par défaut, une page intégrée peut exécuter des scripts, soumettre des formulaires, ouvrir des fenêtres contextuelles, naviguer dans la page de niveau supérieur et lire les cookies de sa propre origine. Lorsque vous intégrez du contenu que vous ne contrôlez pas totalement, cela représente un risque de sécurité. L'attribut sandbox applique un ensemble strict de restrictions, puis vous permet de réactiver uniquement les capacités dont le cadre a réellement besoin en listant des tokens séparés par des espaces.

Un sandbox vide (c'est-à-dire sandbox="") applique toutes les restrictions : pas de scripts, pas de formulaires, pas de fenêtres contextuelles, pas de plugins, et le contenu est forcé dans une origine opaque unique. Vous l'assouplissez ensuite token par token :

Token	Réactive
`allow-forms`	La soumission de formulaires.
`allow-same-origin`	Le traitement du contenu comme étant de même origine (afin qu'il puisse utiliser ses propres cookies et son stockage).
`allow-scripts`	L'exécution de JavaScript.
`allow-popups`	L'ouverture de nouvelles fenêtres ou onglets (par ex. `window.open`, `target="_blank"`).
`allow-downloads`	Le déclenchement de téléchargements de fichiers.
`allow-modals`	L'affichage de boîtes de dialogue modales comme `alert()`, `confirm()` et `prompt()`.
`allow-top-navigation`	La navigation dans le contexte de navigation de niveau supérieur (la page parente).
`allow-pointer-lock`	L'utilisation de l'API Pointer Lock.

Combinez allow-scripts et allow-same-origin avec prudence : accorder les deux à du contenu provenant d'une autre origine permet effectivement à ce contenu de supprimer son propre sandbox, donc ne le faites que pour du contenu en lequel vous avez confiance.

Exemple d'une `<iframe>` sandboxée

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

Ici, le widget peut exécuter des scripts et soumettre des formulaires, mais il ne peut pas naviguer dans la page parente, ouvrir des fenêtres contextuelles ni accéder aux cookies et au stockage de même origine.

Accorder des fonctionnalités du navigateur avec l'attribut allow

Tandis que sandbox contrôle les restrictions de base du contexte de navigation, l'attribut allow définit une Permissions Policy pour le cadre — il détermine quelles fonctionnalités puissantes du navigateur (caméra, microphone, géolocalisation, plein écran, lecture automatique, etc.) le document intégré peut utiliser. La plupart de ces fonctionnalités sont bloquées dans les iframes d'origines croisées, sauf si vous les autorisez explicitement avec allow.

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

Cela accorde au cadre la permission de passer en plein écran tout en refusant explicitement l'accès à la caméra. Vous pouvez limiter une fonctionnalité à des origines spécifiques, par ex. allow="geolocation 'self' https://maps.example.com".

Accessibilité

Chaque <iframe> devrait avoir un attribut title qui décrit brièvement la finalité du cadre. Les lecteurs d'écran annoncent le titre afin que les utilisateurs comprennent la nature du contenu intégré avant d'y accéder ; sans titre, le cadre est annoncé comme un simple "frame" sans label, ce qui prête à confusion.

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

Utilisez un titre concis et unique pour chaque iframe sur la page (par exemple "Sondage de satisfaction client" plutôt que simplement "iframe").

Quand une page refuse d'être intégrée

L'intégration ne réussit pas toujours : la page vers laquelle pointe src peut refuser d'être affichée dans un cadre. Les sites font cela pour prévenir le clickjacking, où un attaquant superpose un cadre caché sur leur propre interface. Une page peut refuser d'être intégrée de deux façons :

L'en-tête de réponse HTTP X-Frame-Options (hérité) (DENY ou SAMEORIGIN).
La directive moderne frame-ancestors de Content-Security-Policy, par ex. Content-Security-Policy: frame-ancestors 'self'.

Si un site cible envoie l'un ou l'autre de ces en-têtes, votre iframe affichera un cadre vide ou une erreur au lieu du contenu — c'est le comportement attendu, pas un bug dans votre balisage. De nombreux sites importants (banques, réseaux sociaux) bloquent l'intégration dans des cadres pour des raisons de sécurité, c'est pourquoi vous ne pouvez pas les intégrer directement.

Attributs

Attribut	Valeur	Description
align	left right top bottom middle	Spécifie comment le texte est aligné et s'adapte autour du cadre. Non pris en charge en HTML5.
allow	string	Spécifie une politique qui autorise ou restreint certaines fonctionnalités dans l'iframe.
allowfullscreen		Définit que le cadre peut être ouvert en mode plein écran.
frameborder	1 0	Définit si la bordure de l'iframe autour du cadre doit être affichée ou non. Non pris en charge en HTML5.
height	pixels	Définit la hauteur du cadre (hauteur par défaut 150px).
longdesc	URL	Définit une page contenant une longue description du contenu. Non pris en charge en HTML5.
marginheight	pixels	Définit les marges supérieure et inférieure du cadre. Non pris en charge en HTML5.
marginwidth	pixels	Définit les marges gauche et droite du cadre. Non pris en charge en HTML5.
loading	eager lazy	Définit si le cadre se charge immédiatement ou est différé jusqu'à ce qu'il soit proche du viewport.
name	text	Définit le nom du cadre (une cible pour les liens et les formulaires).
referrerpolicy	keyword	Définit quelles informations de référent envoyer avec la requête. Prend un mot-clé tel que `no-referrer`, `origin` ou `strict-origin-when-cross-origin` — pas une URL.
sandbox	token list	Applique des restrictions supplémentaires au contenu du cadre. Vide (`sandbox=""`) applique toutes les restrictions ; ajoutez des tokens séparés par des espaces comme `allow-scripts` ou `allow-forms` pour les assouplir. Voir la section sandbox.
scrolling	yes no auto	Définit si la barre de défilement doit être affichée ou non. Non pris en charge en HTML5.
seamless	seamless	Spécifie que le contenu du document attaché doit être affiché comme faisant partie du document parent.
src	URL	Spécifie l'adresse du document dont le contenu sera chargé dans le cadre.
srcdoc	HTML code	Stocke le contenu du cadre directement dans l'attribut, au lieu de charger une URL séparée.
title	text	Décrit le contenu du cadre pour les technologies d'assistance. Doit être présent sur chaque iframe.
width	pixels	Définit la largeur du cadre. (la largeur par défaut est 300px).

La balise <iframe> prend en charge les attributs globaux et les attributs d'événements.

Balises associées

Balise HTML <frame> — définit un cadre unique dans un <frameset> (framesets hérités, obsolètes en HTML5).
Balise HTML <embed> — intègre du contenu externe tel qu'un plugin ou une ressource multimédia.

Pratique

Quel attribut doit figurer sur chaque iframe pour que les lecteurs d'écran puissent annoncer son objectif ?

title : Décrit le contenu du cadre pour les technologies d'assistance.name : Définit le nom de l'iframe.align : Un attribut HTML5 obsolète qui positionnait le cadre à gauche ou à droite.src : Spécifie l'URL du document à intégrer.

Syntaxe

Exemple de balise HTML <iframe>

Exemple de balise HTML <iframe> avec les attributs Height et Width

Exemple de balise HTML <iframe> avec la propriété CSS Border

Intégrer du HTML en ligne avec srcdoc

Chargement différé des iframes hors écran

Restreindre le contenu avec l'attribut sandbox

Exemple d'une <iframe> sandboxée

Accorder des fonctionnalités du navigateur avec l'attribut allow

Accessibilité

Quand une page refuse d'être intégrée

Attributs

Balises associées

Pratique

Exemple de balise HTML `<iframe>`

Exemple de balise HTML `<iframe>` avec les attributs Height et Width

Exemple de balise HTML `<iframe>` avec la propriété CSS Border

Exemple d'une `<iframe>` sandboxée