Tag HTML <iframe>
A tag HTML <iframe> incorpora outro documento inline. Aprenda seus atributos, sandbox, allow e carregamento lazy.
A tag <iframe> (abreviação de inline frame) incorpora outro documento HTML dentro da página atual. É a forma padrão de exibir conteúdo de terceiros, como um player de vídeo, um mapa, um anúncio ou um widget isolado. O documento incorporado é carregado em um contexto de navegação aninhado, independente da página hospedeira, mas os dois podem interagir via JavaScript quando compartilham a mesma origem.
Esta página aborda a sintaxe do <iframe>, seus atributos, como dimensionar e estilizar um frame, o carregamento lazy nativo do navegador e os dois recursos que você deve usar sempre que incorporar conteúdo que não controla totalmente: sandbox e allow.
Para incorporar recursos não-HTML, veja também as tags <embed> e <frame>.
Sintaxe
A tag <iframe> é um elemento HTML comum que exige uma tag de fechamento. Sempre adicione o atributo title (veja Acessibilidade abaixo).
Exemplo de uma 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>Para definir o tamanho do iframe, use os atributos de altura e largura, ou use CSS. Os valores dos atributos são definidos em pixels por padrão, mas também podem estar em porcentagem.
Exemplo de uma Tag HTML <iframe> com os Atributos de Altura e Largura
<!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>Os navegadores modernos não aplicam uma borda padrão aos iframes. Você ainda pode usar a propriedade CSS border para estilizar o frame, se necessário.
Exemplo de uma Tag HTML <iframe> com a Propriedade 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>Incorporando HTML inline com srcdoc
Em vez de apontar para uma URL com src, você pode fornecer toda a marcação do frame inline usando o atributo srcdoc. Isso é útil para pré-visualizações, trechos isolados ou HTML gerado dinamicamente onde você não tem um arquivo ou URL separados. Quando ambos os atributos estão presentes, srcdoc tem precedência (com src sendo usado como alternativa para navegadores que não suportam srcdoc).
<iframe
title="Inline greeting"
srcdoc="<!DOCTYPE html><html><body><h1>Hello from srcdoc!</h1></body></html>">
</iframe>Como a marcação fica em um atributo HTML, as aspas duplas literais dentro dela devem ser escritas como " e os ampersands como &.
Carregamento lazy de iframes fora da tela
O atributo loading permite que o navegador adie o carregamento de um iframe até que ele esteja prestes a entrar na área visível. O carregamento lazy nativo já é um padrão web estável, suportado em todos os navegadores modernos desde cerca de 2020, então você não precisa mais de uma biblioteca JavaScript para esse caso comum.
Valores suportados:
lazy— adia o carregamento até que o iframe esteja próximo do viewport. Recomendado para frames fora da tela (players de vídeo, mapas, espaços de anúncio) que não são visíveis na primeira renderização.eager— carrega o recurso imediatamente, independentemente de sua posição. Este é o padrão.
<iframe src="video-player.html" title="Promo video" loading="lazy"></iframe>Adiar iframes fora da tela reduz o peso inicial da página, acelera o primeiro carregamento e evita gastar a largura de banda do usuário em conteúdo que ele pode nunca rolar até ver.
Restringindo conteúdo com o atributo sandbox
Por padrão, uma página incorporada pode executar scripts, enviar formulários, abrir pop-ups, navegar na página de nível superior e ler cookies de sua própria origem. Quando você incorpora conteúdo que não controla totalmente, isso representa um risco de segurança. O atributo sandbox aplica um conjunto rigoroso de restrições e permite que você reabilite apenas as capacidades que o frame realmente precisa, listando tokens separados por espaço.
Um sandbox vazio (ou seja, sandbox="") aplica todas as restrições: nenhum script, nenhum formulário, nenhum pop-up, nenhum plugin, e o conteúdo é forçado a uma origem opaca única. Você então afrouxa essas restrições token por token:
| Token | Reabilita |
|---|---|
allow-forms | Envio de formulários. |
allow-same-origin | Tratar o conteúdo como mesma origem (para que ele possa usar seus próprios cookies e armazenamento). |
allow-scripts | Executar JavaScript. |
allow-popups | Abrir novas janelas ou abas (ex.: window.open, target="_blank"). |
allow-downloads | Acionar downloads de arquivos. |
allow-modals | Exibir caixas de diálogo modais como alert(), confirm() e prompt(). |
allow-top-navigation | Navegar no contexto de navegação de nível superior (a página pai). |
allow-pointer-lock | Usar a Pointer Lock API. |
Combine allow-scripts e allow-same-origin com cuidado: conceder ambos a conteúdo de outra origem efetivamente permite que esse conteúdo remova seu próprio sandbox, então faça isso apenas para conteúdo em que você confia.
Exemplo de um <iframe> com 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>Aqui o widget pode executar scripts e enviar formulários, mas não pode navegar na página pai, abrir pop-ups nem acessar cookies e armazenamento da mesma origem.
Concedendo recursos do navegador com o atributo allow
Enquanto sandbox controla as restrições básicas do contexto de navegação, o atributo allow define uma Política de Permissões para o frame — ele decide quais recursos avançados do navegador (câmera, microfone, geolocalização, tela cheia, reprodução automática, etc.) o documento incorporado pode usar. A maioria desses recursos é bloqueada em iframes de origens cruzadas, a menos que você opte por habilitá-los com allow.
<iframe
src="https://example.com/player.html"
title="Video player"
allow="fullscreen; camera 'none'">
</iframe>Isso concede ao frame permissão para entrar em tela cheia enquanto nega explicitamente o acesso à câmera. Você pode limitar um recurso a origens específicas, por exemplo allow="geolocation 'self' https://maps.example.com".
Acessibilidade
Todo <iframe> deve ter um atributo title que descreva brevemente o propósito do frame. Os leitores de tela anunciam o título para que os usuários entendam o que é o conteúdo incorporado antes de acessá-lo; sem um título, o frame é anunciado apenas como um "frame" sem rótulo, o que é confuso.
<iframe src="map.html" title="Map showing our office location"></iframe>Use um título conciso e único para cada iframe na página (por exemplo, "Pesquisa de satisfação do cliente" em vez de apenas "iframe").
Quando uma página se recusa a ser enquadrada
A incorporação nem sempre funciona: a página para a qual src aponta pode se recusar a ser exibida dentro de um frame. Os sites fazem isso para evitar o clickjacking, em que um atacante sobrepõe um frame oculto sobre sua própria interface. Uma página pode optar por não ser enquadrada de duas formas:
- O cabeçalho de resposta HTTP legado
X-Frame-Options(DENYouSAMEORIGIN). - A diretiva
frame-ancestorsda Content-Security-Policy moderna, por exemploContent-Security-Policy: frame-ancestors 'self'.
Se um site de destino enviar qualquer um desses cabeçalhos, seu iframe exibirá um frame em branco ou com erro em vez do conteúdo — esse é o comportamento esperado, não um bug na sua marcação. Muitos grandes sites (bancos, redes sociais) bloqueiam o enquadramento por segurança, por isso você não pode incorporá-los diretamente.
Atributos
| Atributo | Valor | Descrição |
|---|---|---|
| align | left right top bottom middle | Especifica como o texto é alinhado e envolvido ao redor do frame. Não suportado no HTML5. |
| allow | string | Especifica uma política que permite ou restringe determinados recursos no iframe. |
| allowfullscreen | Define que o frame pode ser aberto em modo de tela cheia. | |
| frameborder | 1 0 | Define se a borda ao redor do frame deve ser exibida ou não. Não suportado no HTML5. |
| height | pixels | Define a altura do frame (altura padrão de 150px). |
| longdesc | URL | Define uma página com uma descrição longa do conteúdo. Não suportado no HTML5. |
| marginheight | pixels | Define as margens superior e inferior do frame. Não suportado no HTML5. |
| marginwidth | pixels | Define as margens esquerda e direita do frame. Não suportado no HTML5. |
| loading | eager lazy | Define se o frame carrega imediatamente ou é adiado até estar próximo do viewport. |
| name | text | Define o nome do frame (um destino para links e formulários). |
| referrerpolicy | keyword | Define quais informações de referenciador enviar com a requisição. Aceita uma palavra-chave como no-referrer, origin ou strict-origin-when-cross-origin — não uma URL. |
| sandbox | token list | Aplica restrições extras ao conteúdo do frame. Vazio (sandbox="") aplica todas as restrições; adicione tokens separados por espaço como allow-scripts ou allow-forms para relaxá-las. Veja a seção sandbox. |
| scrolling | yes no auto | Define se a barra de rolagem deve ser exibida ou não. Não suportado no HTML5. |
| seamless | seamless | Especifica que o conteúdo do documento anexado deve ser exibido como parte do documento pai. |
| src | URL | Especifica o endereço do documento cujo conteúdo será carregado no frame. |
| srcdoc | HTML code | Armazena o conteúdo do frame diretamente no atributo, em vez de carregar uma URL separada. |
| title | text | Descreve o conteúdo do frame para tecnologias assistivas. Deve estar presente em todo iframe. |
| width | pixels | Define a largura do frame (largura padrão de 300px). |
A tag <iframe> suporta os Atributos Globais e os Atributos de Evento.
Tags relacionadas
- Tag HTML
<frame>— define um único frame dentro de um<frameset>(framesets legados, obsoleto no HTML5). - Tag HTML
<embed>— incorpora conteúdo externo como um plugin ou recurso de mídia.