Referencia de etiquetas

Etiqueta iframe en HTML: documentos incrustados y límites

La etiqueta <iframe> incorpora otro documento HTML en un contexto de navegación separado dentro de la página. Sirve para consultar una ficha, un mapa o un contenido proporcionado por otro servicio sin abandonar inicialmente el documento principal. Úsala cuando necesitas esa página independiente y tienes permiso para incrustarla; si solo quieres llevar al lector hasta ella, basta un enlace.

Ejemplo mínimo: mostrar una ficha local

Este ejemplo utiliza la ficha del curso incluida en el sitio. Más abajo encontrarás su código completo. Para copiarlo, guarda ese documento en /ejemplos/ficha.html de tu servidor o cambia src por la URL de tu propia página.

<iframe src="/ejemplos/ficha.html" title="Ficha del curso de HTML"
  width="640" height="360" loading="lazy"></iframe>

Cuando existe el archivo, aparece la ficha dentro de un marco de 640 por 360 píxeles CSS, con su propio desplazamiento si lo necesita. title identifica el contenido del marco; no es un encabezado visible. El documento incrustado conserva sus propios estilos: la hoja CSS del padre no modifica automáticamente sus párrafos.

Cambiar src solicita otra página. Cambiar las dimensiones altera el espacio disponible, no el contenido. Al retirar <iframe>, desaparece la vista incrustada. Para conservar el acceso, añade un enlace fuera del elemento, como en el caso práctico.

Sintaxis y contexto válido

Escribe apertura y cierre: <iframe ...></iframe>. Ninguna etiqueta puede omitirse y /> no cierra este elemento en HTML. Aunque lleva cierre, su modelo de contenido es vacío: no coloques HTML hijo entre las etiquetas. Ese texto no funciona como una alternativa visible normal cuando falla la carga.

Puede aparecer donde se admita contenido incrustado, por ejemplo dentro de una sección. Es contenido interactivo: evita incluirlo dentro de un enlace o un botón. El estándar de iframe define estos contextos y restricciones.

Para elegir el documento, usa src con una URL o srcdoc con HTML escrito en el propio atributo. Si ambos están presentes, srcdoc tiene prioridad. Sin ninguno, el marco queda inicialmente en about:blank.

Srcdoc: un documento estático sin otro archivo

Esta variante muestra una nota escrita por el autor y no necesita descargar una ficha:

<iframe title="Nota sobre la primera clase" sandbox
  srcdoc="&lt;!doctype html&gt;&lt;html lang='es'&gt;
  &lt;head&gt;&lt;meta charset='utf-8'&gt;&lt;title&gt;Nota del curso&lt;/title&gt;&lt;/head&gt;
  &lt;body&gt;&lt;p&gt;Primera clase: estructura HTML.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;">
</iframe>

Los escapes se convierten en marcado para el documento interior. Si agregas src="/ejemplos/ficha.html", seguirá apareciendo la nota; al quitar srcdoc, se cargará la ficha. Las rutas relativas de un documento srcdoc se resuelven usando la URL del documento que lo incrusta.

Este ejemplo contiene HTML fijo y sandbox vacío. No concatenes entradas no confiables en srcdoc: se interpretan como HTML y pueden introducir código peligroso. La referencia de srcdoc y sus riesgos explica por qué hay que sanear esas entradas y aplicar restricciones adecuadas.

Atributos del marco y su documento

Atributo específico	Función y valores útiles
`src`	URL del documento que se quiere cargar.
`srcdoc`	HTML del documento interior; prevalece sobre `src`.
`width`, `height`	Dimensiones en píxeles CSS como enteros no negativos. Sin otras dimensiones, el tamaño predeterminado es 300 por 150.
`loading`	`eager` es el valor predeterminado; `lazy` permite diferir la carga según la proximidad al área visible.
`sandbox`	Activa restricciones; sus palabras separadas por espacios permiten levantar algunas. Ausente y vacío producen comportamientos distintos.
`allow`	Define una política de permisos para capacidades concretas, por ejemplo `allow="fullscreen"`.
`allowfullscreen`	Atributo booleano para permitir el uso de pantalla completa. Su presencia lo activa: `allowfullscreen="false"` no lo desactiva.
`name`	Nombre del contexto que puede usarse como destino de un enlace con `target`. No sustituye al título accesible.
`referrerpolicy`	Controla la información de referencia enviada al solicitar el documento. `no-referrer` omite la cabecera `Referer`.

title, class, id y lang son atributos globales. Para una anchura adaptable, usa la propiedad CSS width: 100%; width="100%" no es una dimensión HTML válida. Ajusta el borde mediante CSS, en lugar del antiguo frameborder.

Según la documentación de carga diferida, lazy no promete un instante exacto de carga y el aplazamiento requiere JavaScript habilitado en el navegador. Eso no obliga a escribir un script: la ficha también puede cargarse con JavaScript desactivado.

Si no se establece otra política, el valor habitual de referencia es strict-origin-when-cross-origin: URL completa al mismo origen, solo origen hacia otro con seguridad equivalente y sin referencia al pasar de HTTPS a HTTP. Consulta los valores de referrerpolicy antes de cambiarlo; ocultar esa cabecera no vuelve anónima la petición.

Origen, sandbox y permisos

El origen combina protocolo, servidor y puerto. Dos páginas de la misma carpeta pueden tener distinto origen si cambia alguno de esos componentes. La política del mismo origen limita qué puede leer o modificar JavaScript entre documentos. Poder ver un sitio en un marco no concede acceso a su DOM.

sandbox="" aplica el conjunto de restricciones: entre otras, bloquea scripts, envíos de formularios y navegación de la página superior, y trata el documento como un origen opaco. Es equivalente a escribir solo sandbox. Sin el atributo no se añaden esas restricciones, aunque permanecen las políticas normales del navegador y del servidor. La referencia de las restricciones sandbox describe también sus excepciones.

Añade únicamente las excepciones necesarias. allow-scripts permite scripts; allow-forms, envíos; allow-top-navigation-by-user-activation, navegar la página superior tras una activación del usuario. Recarga el documento al probar cambios: modificar el atributo no transforma de inmediato todas las restricciones del documento ya cargado.

No combines allow-scripts y allow-same-origin sobre contenido del mismo origen suponiendo aislamiento fuerte: el contenido puede acceder al elemento que lo contiene, retirar el atributo y recargarse. sandbox tampoco impide toda comunicación de red ni sustituye la revisión del contenido.

allow resuelve otro problema: controla capacidades mediante Permissions Policy. No elimina sandbox, no supera una prohibición del servidor y no evita un eventual permiso del usuario. allowfullscreen es la forma histórica de permitir pantalla completa, equivalente a allow="fullscreen *". La API allowFullscreen describe ese permiso.

Caso práctico: ficha adaptable con un permiso mínimo

Puedes abrir el ejemplo completo. Para reproducirlo, guarda la ficha en /ejemplos/ficha.html y la página que la contiene en /ejemplos/iframe/curso.html. Sirve ambos documentos por HTTP: abrirlos como archivos locales mediante file: no reproduce las mismas reglas de origen.

Primero crea /ejemplos/ficha.html:

<!doctype html>
<html lang="es">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Ficha del curso de HTML</title>
  <style>
    body { margin: 0; padding: 1rem; font: 1rem/1.6 system-ui, sans-serif; }
    a:focus-visible { outline: 3px solid #174ea6; outline-offset: 3px; }
  </style>
</head>
<body>
  <h1>Curso de HTML</h1>
  <p>Una introducción a documentos, enlaces y formularios.</p>
  <p><a href="#temario">Consultar el temario</a></p>
  <h2 id="temario">Temario</h2>
  <ol>
    <li>Estructura del documento.</li>
    <li>Enlaces entre páginas.</li>
    <li>Controles de formulario.</li>
  </ol>
  <p><a href="/ejemplos/iframe/curso.html#inscripcion" target="_top">Ver información de inscripción</a></p>
</body>
</html>

Después crea curso.html dentro de la carpeta /ejemplos/iframe/:

<!doctype html>
<html lang="es">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Vista previa del curso de HTML</title>
  <style>
    body {
      max-width: 48rem;
      margin: 0 auto;
      padding: 1rem;
      font: 1rem/1.6 system-ui, sans-serif;
    }
    iframe {
      display: block;
      box-sizing: border-box;
      width: 100%;
      height: 24rem;
      border: 1px solid #65758b;
    }
    a:focus-visible { outline: 3px solid #174ea6; outline-offset: 3px; }
  </style>
</head>
<body>
  <h1>Vista previa del curso</h1>
  <p><a href="/ejemplos/ficha.html">Abrir la ficha como página independiente</a></p>
  <iframe src="/ejemplos/ficha.html" title="Ficha del curso de HTML"
    width="640" height="360" loading="lazy"
    sandbox="allow-top-navigation-by-user-activation"></iframe>
  <p><a href="#inscripcion">Ir a la información de inscripción</a></p>
  <section aria-labelledby="inscripcion">
    <h2 id="inscripcion">Información de inscripción</h2>
    <p>Demostración didáctica: no hay inscripción ni envío de datos.</p>
  </section>
</body>
</html>

La ficha se adapta al ancho disponible; CSS sustituye las dimensiones de los atributos. Su enlace al temario navega dentro del marco. El enlace con target="_top" lleva la página principal hasta la información de inscripción. La excepción de sandbox permite esa navegación al pulsarlo; no se necesitan permisos para scripts, formularios o ventanas nuevas.

Para comprobar las decisiones del ejemplo:

Recorre los enlaces con Tab y Mayús+Tab. Entra en la ficha, activa el temario con Intro y comprueba que puedes salir hacia el enlace posterior del padre.
Activa el enlace de inscripción del documento interior. Debe cambiar el fragmento de la URL principal a #inscripcion.
Cambia a sandbox="" y recarga. El temario sigue funcionando, pero el enlace que intenta navegar la página superior queda bloqueado. Restaura después el permiso.
Prueba anchuras de móvil y escritorio y desactiva JavaScript. Los textos y enlaces conservan su función; puede cambiar cuándo se carga el marco.
Sustituye temporalmente solo src por una URL inexistente. El marco puede mostrar un error, pero el enlace independiente conserva la URL correcta. Al retirar el elemento, ese enlace y la información del padre siguen disponibles.

Accesibilidad del documento incrustado

Usa un title breve y descriptivo, como «Ficha del curso de HTML». WAI distingue el título del marco y el título del documento: el atributo permite identificar el marco y el elemento <title> interior identifica su página. name sirve como destino de navegación, no como reemplazo de ese nombre.

El título exterior no corrige el contenido interior. Conserva idioma, encabezados, enlaces comprensibles y foco visible en la ficha. Comprueba que el recorrido con teclado permite entrar y salir, y que el desplazamiento permite leerla completa. Un enlace fuera del marco ofrece lectura independiente y permanece disponible si la incrustación falla.

Por qué un iframe no muestra una página

Comprueba las causas en este orden:

Abre la URL de src directamente. Revisa errores de ruta, respuestas 404, autenticación y redirecciones.
Comprueba que no exista un srcdoc que esté sustituyendo a src, y revisa altura, anchura y reglas CSS que oculten el marco.
Consulta la consola y las cabeceras de la respuesta. El sitio puede rechazar la incrustación mediante CSP frame-ancestors o X-Frame-Options. La CSP del padre también puede limitar qué documentos carga mediante frame-src.
Si aparece la página pero falla una función, revisa los permisos de sandbox y allow. Un documento que depende de scripts no funcionará completamente cuando estos estén bloqueados.

¿Por qué un sitio rechaza el iframe? Puede permitir visitas directas y prohibir que otras páginas lo incrusten. No hay una solución HTML universal: utiliza su URL de incrustación autorizada, solicita permiso o mantén un enlace. Añadir allow o cambiar sandbox no elude esas cabeceras.

¿Puedo acceder al contenido con JavaScript? Con el mismo origen y sin restricciones que lo impidan, el padre puede consultar iframe.contentDocument. Con otro origen, o con un origen opaco impuesto por sandbox, ese acceso está limitado. Para comunicar documentos cooperantes de distinto origen se utiliza postMessage verificando el origen del mensaje; el marco no concede control sobre una página ajena.

Iframe frente a otras etiquetas

<iframe> muestra un documento con navegación independiente. La etiqueta embed incorpora recursos cuyo tratamiento depende del navegador; la etiqueta object puede ofrecer contenido alternativo interno. Ninguna opción garantiza un visor PDF uniforme. Para una imagen usa <img>: un marco no reemplaza su texto alternativo.

Un enlace con a suele bastar cuando la consulta independiente es más útil. La etiqueta script incorpora o ejecuta código en el documento que lo contiene; por sí mismo no crea el contexto separado de un marco.

Compatibilidad y fuentes

Fuentes consultadas el 3 de octubre de 2026: HTML Living Standard, WAI y las referencias de MDN enlazadas, incluida su tabla de compatibilidad de iframe. El elemento está ampliamente disponible; el soporte de una capacidad concreta, sus permisos y las políticas de un servicio son cuestiones diferentes.