Docs executáveis de HTML: Imagens

Q: Como inserir uma imagem no HTML?

Use a tag com o arquivo em src e uma descrição em alt: . não tem tag de fechamento.

Q: Como mudar o tamanho de uma imagem no HTML?

Defina os atributos width e height em pixels, ou use CSS como img { width: 300px; height: auto; }. Definir só uma dimensão e deixar a outra em auto mantém as proporções.

Q: Por que minha imagem não aparece no HTML?

Normalmente o caminho em src está errado: ele é relativo ao arquivo HTML, os nomes de arquivo diferenciam maiúsculas de minúsculas na maioria dos servidores, e um caminho como C:\photos\cat.jpg só existe no seu computador. Abra a URL da imagem direto no navegador para conferir.

Q: O que é o texto alternativo (alt) no HTML?

O atributo alt é um texto que substitui a imagem. Os leitores de tela o leem, e os navegadores o mostram quando a imagem não carrega. Descreva o que a imagem mostra ou faz; use alt="" para imagens só decorativas.

Q: Como deixar uma imagem responsiva?

Adicione max-width: 100%; height: auto; a ela no CSS. A imagem então encolhe para caber num contêiner estreito e nunca cresce além da sua largura natural.

Como inserir uma imagem no HTML

Use o elemento <img>. src é o arquivo da imagem, alt a descreve, e width e height dão o tamanho em pixels. <img> é um elemento vazio: não tem tag de fechamento.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Image</title>
</head>
<body>
  <img
    src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='300' height='200'%3E%3Crect width='300' height='200' fill='%23bfdbfe'/%3E%3Ccircle cx='230' cy='60' r='28' fill='%23f59e0b'/%3E%3Cpath d='M0 150 Q80 90 160 140 T300 130 V200 H0Z' fill='%2316a34a'/%3E%3C/svg%3E"
    alt="Green hills under a yellow sun"
    width="300"
    height="200">
</body>
</html>

O src aqui é um SVG pequeno escrito dentro da URL (uma data URI) para que o exemplo funcione offline. Num site real, src é um caminho para um arquivo:

`src`	Carrega
`photo.jpg`	`photo.jpg` na mesma pasta do arquivo HTML
`images/photo.jpg`	Da pasta `images` ao lado do arquivo HTML
`../photo.jpg`	De uma pasta acima
`/images/photo.jpg`	Da pasta `images` na raiz do site
`https://example.com/photo.jpg`	De outro site (a imagem pode mudar de lugar ou sumir)

Os caminhos diferenciam maiúsculas de minúsculas na maioria dos servidores web: Photo.JPG e photo.jpg são arquivos diferentes.

Texto alternativo

O texto de alt substitui a imagem. Os leitores de tela o leem em voz alta, e o navegador o mostra quando a imagem não carrega. As duas imagens aqui apontam para arquivos que não existem:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Alt text</title>
  <style>
    img { border: 2px dashed #e5e7eb; }
  </style>
</head>
<body>
  <p><img src="missing-logo.png" alt="Coddy logo" width="160" height="60"></p>
  <p><img src="missing-chart.png" alt="" width="160" height="60"> (decorative, empty alt)</p>
</body>
</html>

A primeira mostra o seu texto alternativo, "Coddy logo", onde a imagem deveria estar. A segunda tem um alt vazio, então não há texto para mostrar, e os leitores de tela a ignoram. Como escrever o alt:

Descreva o que importa no contexto. "Gráfico de barras: as vendas dobraram de março a junho" diz mais que "gráfico".
Não comece com "Imagem de". Os leitores de tela já anunciam que é uma imagem.
Use alt="" para decoração (um divisor, um enfeite de fundo) para que os leitores de tela a ignorem.
Nunca deixe o alt de fora. Sem ele, alguns leitores de tela leem o nome do arquivo, algo como "IMG underline 4032 ponto jpg".
Para uma imagem dentro de um link, descreva o destino: <a href="/"><img src="logo.svg" alt="Home"></a>.

Definindo o tamanho da imagem

Os atributos width e height são em pixels, sem unidade. Tamanhos definidos no CSS os substituem. O CSS mais útil para imagens é este par, que deixa a imagem encolher junto com o contêiner mas nunca esticar além da largura natural:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Image size</title>
  <style>
    .box { width: 180px; border: 2px solid #2563eb; margin-bottom: 12px; }
    .responsive { max-width: 100%; height: auto; }
  </style>
</head>
<body>
  <div class="box">
    <img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='300' height='200'%3E%3Crect width='300' height='200' fill='%23bfdbfe'/%3E%3Ccircle cx='230' cy='60' r='28' fill='%23f59e0b'/%3E%3C/svg%3E"
      alt="Overflowing" width="300" height="200">
  </div>
  <div class="box">
    <img class="responsive" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='300' height='200'%3E%3Crect width='300' height='200' fill='%23bfdbfe'/%3E%3Ccircle cx='230' cy='60' r='28' fill='%23f59e0b'/%3E%3C/svg%3E"
      alt="Fits" width="300" height="200">
  </div>
</body>
</html>

A primeira imagem mantém os seus 300 pixels e sai da caixa de 180 pixels. A segunda diminui para 180 por 120, mantendo a proporção 3:2. height: auto faz diferença: sem ele, o atributo height="200" manteria a imagem com 200 pixels de altura e a achataria.

Sempre escreva width e height no HTML, mesmo em imagens responsivas. O navegador os usa para reservar o espaço certo antes de o arquivo chegar, e o texto abaixo não pula quando a imagem carrega.

Recortando com object-fit

Quando uma imagem precisa preencher uma caixa de outro formato (um avatar quadrado a partir de uma foto larga, cards da mesma altura), object-fit decide o que acontece com o que sobra:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>object-fit</title>
  <style>
    body { font-family: system-ui, sans-serif; display: flex; flex-wrap: wrap; gap: 12px; }
    figure { margin: 0; text-align: center; }
    img { width: 120px; height: 120px; border: 2px solid #111827; display: block; }
  </style>
</head>
<body>
  <figure>
    <img style="object-fit: fill" alt="" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='300' height='150'%3E%3Crect width='300' height='150' fill='%23bfdbfe'/%3E%3Ccircle cx='150' cy='75' r='50' fill='%23f59e0b'/%3E%3C/svg%3E">
    <figcaption>fill</figcaption>
  </figure>
  <figure>
    <img style="object-fit: contain" alt="" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='300' height='150'%3E%3Crect width='300' height='150' fill='%23bfdbfe'/%3E%3Ccircle cx='150' cy='75' r='50' fill='%23f59e0b'/%3E%3C/svg%3E">
    <figcaption>contain</figcaption>
  </figure>
  <figure>
    <img style="object-fit: cover" alt="" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='300' height='150'%3E%3Crect width='300' height='150' fill='%23bfdbfe'/%3E%3Ccircle cx='150' cy='75' r='50' fill='%23f59e0b'/%3E%3C/svg%3E">
    <figcaption>cover</figcaption>
  </figure>
</body>
</html>

A origem é uma imagem 2:1 de um círculo, mostrada em caixas quadradas:

fill (o padrão) estica a imagem até a caixa, então o círculo vira uma oval.
contain encaixa a imagem inteira dentro, deixando faixas vazias.
cover preenche a caixa e corta o excesso, mantendo o círculo redondo. É a escolha comum para miniaturas e avatares.

object-position escolhe qual parte fica visível no recorte, por exemplo object-position: top para retratos.

Legendas com figure e figcaption

Uma legenda que pertence a uma imagem vai em <figcaption>, e as duas vão dentro de <figure>. Isso as liga para os leitores de tela, e a figura pode ser estilizada como uma unidade:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Figure</title>
  <style>
    figure { display: inline-block; margin: 0; padding: 8px; border: 1px solid #e5e7eb; }
    img { display: block; }
    figcaption { font: 14px system-ui, sans-serif; color: #4b5563; padding-top: 6px; }
  </style>
</head>
<body>
  <figure>
    <img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='240' height='120'%3E%3Crect width='240' height='120' fill='%23e5e7eb'/%3E%3Crect x='20' y='70' width='40' height='40' fill='%232563eb'/%3E%3Crect x='80' y='40' width='40' height='70' fill='%232563eb'/%3E%3Crect x='140' y='20' width='40' height='90' fill='%232563eb'/%3E%3C/svg%3E"
      alt="Bar chart: signups rose each quarter" width="240" height="120">
    <figcaption>Figure 1. Signups per quarter.</figcaption>
  </figure>
</body>
</html>

A legenda não substitui o alt. O alt diz o que a imagem mostra; a legenda acrescenta o que um leitor que enxerga também precisaria saber.

O espaço embaixo de uma imagem

Uma imagem fica na linha de base do texto, como uma letra, então o contêiner deixa espaço embaixo dela para as partes descendentes de letras como g e y. Uma borda deixa o espaço visível:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Gap under image</title>
  <style>
    div { display: inline-block; border: 2px solid #dc2626; margin-inline-end: 12px; }
    .fixed img { display: block; }
  </style>
</head>
<body>
  <div><img alt="" width="100" height="60" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='60'%3E%3Crect width='100' height='60' fill='%232563eb'/%3E%3C/svg%3E"></div>
  <div class="fixed"><img alt="" width="100" height="60" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='60'%3E%3Crect width='100' height='60' fill='%232563eb'/%3E%3C/svg%3E"></div>
</body>
</html>

A primeira borda tem uma faixa branca embaixo da imagem azul. display: block na imagem (segunda caixa) a remove; vertical-align: middle também, se a imagem precisar continuar inline.

Lazy loading e fontes responsivas

Para imagens mais abaixo numa página longa, loading="lazy" adia o download até o leitor rolar para perto delas:

<img src="gallery-7.jpg" alt="Harbor at dusk" width="800" height="533" loading="lazy">

Não use lazy loading na imagem principal do topo da página; isso atrasa a parte da página que o leitor vê primeiro.

Para enviar arquivos menores a telas pequenas, liste vários tamanhos em srcset e diga ao navegador com que largura a imagem será exibida com sizes. O navegador escolhe o arquivo:

<img
  src="photo-800.jpg"
  srcset="photo-400.jpg 400w, photo-800.jpg 800w, photo-1600.jpg 1600w"
  sizes="(max-width: 600px) 100vw, 600px"
  alt="Harbor at dusk" width="800" height="533">

<picture> vai além e oferece formatos diferentes, com o <img> como alternativa, que também carrega o alt:

<picture>
  <source srcset="photo.avif" type="image/avif">
  <source srcset="photo.webp" type="image/webp">
  <img src="photo.jpg" alt="Harbor at dusk" width="800" height="533">
</picture>

Formatos de imagem

Formato	Bom para
JPEG	Fotos
PNG	Capturas de tela, imagens que precisam de bordas nítidas ou transparência
WebP	Fotos e gráficos, menor que JPEG e PNG, com transparência
AVIF	Fotos, normalmente menor que WebP
SVG	Logos, ícones e diagramas; escala para qualquer tamanho sem borrar
GIF	Animações curtas, embora um `<video>` mudo em loop seja bem menor

Erros comuns

Um caminho do seu próprio computador, como src="C:\Users\me\photo.jpg". Só funciona na sua máquina. Coloque o arquivo ao lado do HTML e use um caminho relativo.
Falta de alt. Todo <img> precisa de um, vazio para decoração.
Definir width e height no CSS com valores de outra proporção. A imagem estica. Defina um e deixe o outro em auto, ou use object-fit.
Sem os atributos width e height, então a página pula enquanto as imagens carregam.
Arquivos enormes reduzidos com CSS. Uma foto de 4000 pixels exibida com 400 pixels ainda é baixada inteira. Redimensione, ou use srcset.
Uma tag de fechamento </img>. <img> é vazia; não há nada para fechar.

As imagens dos exemplos acima são pequenos SVGs inline. Para testar o mesmo código com as suas fotos, cole-o no playground de HTML.

Perguntas frequentes

Como inserir uma imagem no HTML?

Use a tag <img> com o arquivo em src e uma descrição em alt: <img src="photo.jpg" alt="A red bicycle" width="600" height="400">. <img> não tem tag de fechamento.

Como mudar o tamanho de uma imagem no HTML?

Defina os atributos width e height em pixels, ou use CSS como img { width: 300px; height: auto; }. Definir só uma dimensão e deixar a outra em auto mantém as proporções.

Por que minha imagem não aparece no HTML?

Normalmente o caminho em src está errado: ele é relativo ao arquivo HTML, os nomes de arquivo diferenciam maiúsculas de minúsculas na maioria dos servidores, e um caminho como C:\photos\cat.jpg só existe no seu computador. Abra a URL da imagem direto no navegador para conferir.

O que é o texto alternativo (alt) no HTML?

O atributo alt é um texto que substitui a imagem. Os leitores de tela o leem, e os navegadores o mostram quando a imagem não carrega. Descreva o que a imagem mostra ou faz; use alt="" para imagens só decorativas.

Como deixar uma imagem responsiva?

Adicione max-width: 100%; height: auto; a ela no CSS. A imagem então encolhe para caber num contêiner estreito e nunca cresce além da sua largura natural.

Por que tem um espaço embaixo da minha imagem?

Imagens são inline por padrão e ficam na linha de base do texto, o que deixa espaço embaixo para as partes descendentes das letras. Defina display: block na imagem, ou vertical-align: middle, para remover o espaço.

Conceitos relacionados