Docs executáveis de HTML: Tag iframe

Q: O que é um iframe no HTML?

Um (inline frame) é uma caixa que mostra uma página web separada dentro da página atual. Ele tem o seu próprio documento, estilos e scripts, e por isso é usado para conteúdo incorporado como vídeos, mapas, anúncios e prévias de código.

Q: Por que meu iframe diz que o site recusou a conexão?

O site envia um cabeçalho X-Frame-Options ou Content-Security-Policy: frame-ancestors que proíbe outros sites de colocá-lo num frame. Muitos sites fazem isso para evitar clickjacking. Você não consegue contornar isso pela sua página; use a URL oficial de incorporação do site, se houver.

Q: Como tirar a borda de um iframe?

Defina border: 0 no CSS. O antigo atributo frameborder="0" está obsoleto, embora muitos códigos de incorporação copiados ainda o tragam.

Q: Como deixar um iframe responsivo?

Dê a ele width: 100% e um aspect-ratio no CSS, por exemplo aspect-ratio: 16 / 9 para vídeo, e deixe de fora uma altura fixa. O iframe então acompanha o contêiner e mantém o formato.

Q: O que o atributo sandbox faz num iframe?

Um atributo sandbox vazio bloqueia scripts, envio de formulários, popups e mais dentro do frame, e trata o conteúdo como vindo de uma origem única. Aí você libera só o que o conteúdo precisa com palavras-chave como allow-scripts ou allow-forms.

Como usar um iframe

Um <iframe> mostra outra página dentro da sua. Dê a ele o endereço da página em src, um title que a descreva e um tamanho:

<iframe src="https://example.com/" title="Example site" width="600" height="400"></iframe>

O frame carrega a página como um documento separado, com os seus próprios estilos e scripts. Os exemplos desta página usam srcdoc em vez de src, o que coloca o HTML do frame direto no atributo, então eles funcionam sem carregar outro site:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>iframe</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    p { color: #2563eb; font-weight: 600; }
  </style>
</head>
<body>
  <p>This paragraph is in the outer page.</p>
  <iframe title="Inner page" width="320" height="120"
    srcdoc="<h1 style='font: 20px system-ui'>Hello from inside the frame</h1><p>The outer page's CSS does not reach me.</p>">
  </iframe>
</body>
</html>

O parágrafo de fora é azul e em negrito; o parágrafo dentro do frame não, embora a mesma regra de p esteja na página. Os estilos nunca atravessam a fronteira do frame, em nenhuma direção. A borda padrão e o tamanho padrão de 300×150 vêm do navegador; os atributos width e height substituem o tamanho.

Incorporar um vídeo do YouTube ou um mapa

Sites de vídeo e serviços de mapa dão a você um código de iframe pronto. No YouTube, aperte Compartilhar, depois Incorporar:

<iframe width="560" height="315"
  src="https://www.youtube.com/embed/VIDEO_ID"
  title="YouTube video player"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen></iframe>

No Google Maps, abra o local, aperte Compartilhar, depois Incorporar um mapa, e copie o iframe do mesmo jeito. Mantenha o title (os leitores de tela o anunciam ao entrar no frame) e troque os tamanhos fixos pelo CSS responsivo abaixo. O atributo allow concede ao frame recursos como autoplay ou tela cheia, que ficam desligados por padrão em páginas incorporadas.

Tamanho, borda e iframes responsivos

Códigos de incorporação copiados usam tamanhos fixos em pixels, que transbordam no celular. width: 100% mais aspect-ratio faz o frame preencher o contêiner e manter o formato, e border: 0 remove a borda inset padrão:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Responsive iframe</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    .embed {
      width: 100%;
      aspect-ratio: 16 / 9;
      border: 0;
      border-radius: 8px;
      background: #111827;
    }
    .wrap { max-width: 480px; }
  </style>
</head>
<body>
  <div class="wrap">
    <iframe class="embed" title="Video placeholder"
      srcdoc="<body style='margin:0;height:100vh;display:grid;place-items:center;color:#fff;font:16px system-ui'>16:9 frame">
    </iframe>
  </div>
</body>
</html>

Troque max-width: 480px por outro valor e o frame mantém o formato 16:9 em qualquer largura. Remova border: 0 para ver a borda padrão do navegador. Os antigos atributos frameborder, scrolling e marginheight estão obsoletos; use CSS.

sandbox: limite o que o frame pode fazer

Um frame pode rodar scripts, enviar formulários e abrir popups como qualquer página. O atributo sandbox tira esses poderes; um sandbox vazio bloqueia quase tudo, e cada palavra-chave devolve uma permissão. Os dois frames abaixo recebem o mesmo HTML com um pequeno script:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>sandbox</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    iframe { width: 240px; height: 70px; border: 2px solid #e5e7eb; border-radius: 6px; }
    code { display: block; margin: 8px 0 4px; }
  </style>
</head>
<body>
  <code>sandbox=""</code>
  <iframe id="a" sandbox="" title="Sandboxed frame"></iframe>
  <code>sandbox="allow-scripts"</code>
  <iframe id="b" sandbox="allow-scripts" title="Frame with scripts allowed"></iframe>
  <script>
    const html = '<p id="s" style="font: 15px system-ui">Scripts are blocked</p>' +
      '<script>document.getElementById("s").textContent = "JavaScript ran";<\/script>';
    document.getElementById('a').srcdoc = html;
    document.getElementById('b').srcdoc = html;
  </script>
</body>
</html>

O primeiro frame mantém o texto provisório porque o seu script nunca roda (o console do Chrome registra uma mensagem "Blocked script execution" para ele). Use sandbox sempre que colocar num frame um conteúdo em que você não confia totalmente, como HTML escrito por usuários, e adicione só as palavras-chave de que ele precisa:

Palavra-chave	Permite
`allow-scripts`	Rodar JavaScript
`allow-forms`	Enviar formulários
`allow-popups`	`window.open` e links com `target="_blank"`
`allow-modals`	`alert()`, `confirm()` e `prompt()`
`allow-same-origin`	Tratar o conteúdo como a sua origem real (cookies, armazenamento)
`allow-top-navigation`	Navegar a aba inteira para fora da sua página

Nunca combine allow-scripts e allow-same-origin para conteúdo da sua própria origem: o script dentro do frame poderia então remover o próprio sandbox.

Conversando com um frame: postMessage

A página externa e o frame são documentos separados. Quando as origens são diferentes, um não consegue mexer no DOM do outro, mas eles podem trocar mensagens. Digite uma mensagem e envie para dentro do frame:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>postMessage</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    iframe { display: block; width: 280px; height: 80px; margin-top: 10px; border: 2px solid #2563eb; border-radius: 6px; }
  </style>
</head>
<body>
  <input id="msg" value="Hello, frame">
  <button id="send">Send</button>
  <iframe id="frame" title="Message receiver" srcdoc="
    <p style='font: 15px system-ui' id='got'>Waiting for a message</p>
    <script>
      addEventListener('message', (e) => {
        document.getElementById('got').textContent = 'Received: ' + e.data;
      });
    </script>">
  </iframe>
  <script>
    document.getElementById('send').onclick = () => {
      const frame = document.getElementById('frame');
      frame.contentWindow.postMessage(document.getElementById('msg').value, '*');
    };
  </script>
</body>
</html>

Em código real, passe a origem exata do frame (como 'https://maps.example.com') em vez de '*', e verifique e.origin no receptor, para que as mensagens só vão para o site que você espera e só venham dele.

Desempenho e quando um site recusa

Lazy loading. Adicione loading="lazy" aos frames mais abaixo na página; o navegador só os carrega quando o leitor rola para perto deles. Cada iframe é um carregamento de página completo, então uma página com muitos conteúdos incorporados fica lenta sem isso.
"Recusou a conexão". Muitos sites (bancos, a maioria das redes sociais, a busca do Google) enviam um cabeçalho X-Frame-Options ou frame-ancestors que proíbe o uso em frames, e o navegador mostra um erro no frame. A sua página não consegue contornar isso. Use a URL oficial de incorporação do site, ou um link.
Acessibilidade. Sempre defina o title. É assim que o leitor de tela nomeia o frame, e uma página com vários frames sem título é difícil de navegar.

Erros comuns

Falta de title. Os leitores de tela anunciam o frame sem nome.
Larguras fixas vindas de um código de incorporação copiado. Troque por width: 100% e aspect-ratio.
Colocar num frame um arquivo de vídeo comum. Para o seu próprio arquivo .mp4, use o elemento video; iframes são para páginas.
Confiar no conteúdo do frame. Adicione sandbox a tudo o que você não escreveu.
Esperar que o CSS de fora estilize o frame. Estilize a página do frame por dentro dela.

Perguntas frequentes

O que é um iframe no HTML?

Um <iframe> (inline frame) é uma caixa que mostra uma página web separada dentro da página atual. Ele tem o seu próprio documento, estilos e scripts, e por isso é usado para conteúdo incorporado como vídeos, mapas, anúncios e prévias de código.

Como incorporar um vídeo do YouTube com iframe?

No YouTube, escolha Compartilhar, depois Incorporar, e copie o código. É um iframe cujo src é https://www.youtube.com/embed/ mais o id do vídeo. Mantenha os atributos title e allowfullscreen, e use aspect-ratio: 16 / 9 com width: 100% no CSS para deixá-lo responsivo.

Por que meu iframe diz que o site recusou a conexão?

O site envia um cabeçalho X-Frame-Options ou Content-Security-Policy: frame-ancestors que proíbe outros sites de colocá-lo num frame. Muitos sites fazem isso para evitar clickjacking. Você não consegue contornar isso pela sua página; use a URL oficial de incorporação do site, se houver.

Como tirar a borda de um iframe?

Defina border: 0 no CSS. O antigo atributo frameborder="0" está obsoleto, embora muitos códigos de incorporação copiados ainda o tragam.

Como deixar um iframe responsivo?

Dê a ele width: 100% e um aspect-ratio no CSS, por exemplo aspect-ratio: 16 / 9 para vídeo, e deixe de fora uma altura fixa. O iframe então acompanha o contêiner e mantém o formato.

O que o atributo sandbox faz num iframe?

Um atributo sandbox vazio bloqueia scripts, envio de formulários, popups e mais dentro do frame, e trata o conteúdo como vindo de uma origem única. Aí você libera só o que o conteúdo precisa com palavras-chave como allow-scripts ou allow-forms.

Conceitos relacionados