21.01.2025

Como Definir uma Imagem Padrão para src Inválido em HTML

Resposta Rápida

Se houver problemas ao carregar a imagem principal na tag <img>, um atributo especial onerror pode ser utilizado para substituí-la por uma imagem alternativa:

<img src="quebrada.jpg" onerror="this.src='padrão.png';" alt="descrição" />

Neste caso, se quebrada.jpg não carregar, a imagem de fallback padrão.png será utilizada. Isso garante uma transição suave para a imagem alternativa e melhora a experiência do usuário.

Usando a Tag HTML Object

Uma alternativa interessante pode ser a tag <object>, que pode embutir a tag <img> para situações em que a imagem principal não está disponível:

<object data="imagem.jpg" type="image/jpeg">
    <img src="padrão.png" alt="descrição" />
</object>

Se o carregamento de imagem.jpg falhar, o usuário verá padrão.png. O suporte à tag <object> pela maioria dos navegadores a torna uma ferramenta confiável.

Brincando com Substituição de Imagens: Tornando-a Interativa

Esta abordagem de tratamento de erros pode ser transformada em um jogo criativo:

<!-- Quem mora aqui, afinal? -->
<object data="coelho-da-páscoa.jpg" type="image/jpeg">
    <!-- Ah, é um ovo de Páscoa! -->
    <img src="ovosdepáscoa.png" alt="descrição" />
</object>

Trabalhando com CSS: Aparição e Desaparecimento de Imagens

Vamos criar um pseudo-elemento com uma imagem padrão usando :before e content em CSS:

.img-container:before {
    content: url('padrão.png');
    display: none;
}

.img-container img {
    display: block;
}

.img-container img:invalid + :before {
    display: block;
    /* E aqui vem nossa imagem padrão! */
}

Dessa forma, a .img-container tem uma imagem de fallback que "ganha vida" via CSS quando a imagem principal está ausente.

Expandindo Horizontes: A Tag <picture>

Para criar imagens responsivas, podemos usar <picture> junto com elementos <source>:

<picture>
    <source srcset="imagem-hero.webp" type="image/webp" />
    <source srcset="imagem-hero.jpg" type="image/jpeg" />
    <img src="padrão.png" alt="Imagem principal" />
</picture>

O navegador selecionará a melhor opção entre as fontes disponíveis. Se nenhuma das imagens for adequada, a imagem de fallback da tag img será utilizada.

Mantenha-se Atualizado: A Responsividade é Fundamental

O atributo media nos permite escolher a imagem mais adequada com base no tamanho da tela:

<picture>
    <source media="(min-width: 800px)" srcset="grande.jpg" />
    <source media="(max-width: 799px)" srcset="pequena.jpg" />
    <img src="padrão.png" alt="descrição" />
</picture>

Humanidade em Primeiro Lugar: Texto Alternativo

Ao formular o texto alternativo no atributo alt, tente ser específico e descritivo. Isso melhorará a acessibilidade:

<img src="quebrada.jpg" onerror="this.src='padrão.png';" alt="Palavras gentis podem ser mais valiosas que ouro." />

Mecanismo onerror Confiável

Se você não estiver usando JavaScript, pode integrar o tratamento de erros diretamente na tag <img>:

<img src="imagem.jpg" onerror="if(this.src != 'padrão.png') this.src='padrão.png';" alt="Descrição da ilustração" />

Garanta que a condição no script onerror seja executada para evitar a criação de um loop de erros.

Na Vanguarda: Verifique a Compatibilidade

Antes de aplicar qualquer método, não se esqueça de verificar se suas tags são suportadas pelo navegador, utilizando recursos como Can I Use.

Brincando com Tons em CSS

Com classes CSS, você pode controlar facilmente várias situações definindo imagens padrão para elas:

.img-error {
    background: url('padrão.png') no-repeat center center;
    display: inline-block; /* ou block, se preferir */
}

Assim, mesmo que haja problemas com a imagem principal, você ainda alcançará um resultado estiloso:

<img src="quebrada.jpg" class="img-error" alt="descrição" />

jQuery Sempre Pronto para Ajudar

Use jQuery para substituição dinâmica de imagens danificadas:

$('img').on('error', function() {
    if (this.src !== 'padrão.png') {
        this.src = 'padrão.png';
    }
});

Apesar de precisar do jQuery, esse script é flexível e rápido devido à sua natureza dinâmica.

Demonstrando Capacidades do CSS

Torne seu projeto mais leve utilizando CSS para tratamento de erros:

.img-error:after {
    content: '';
    background-image: url('padrão.png');
    /* Adicione estilos adicionais para o contêiner aqui */
}

Se você está tentando minimizar o uso de JavaScript, o CSS pode ser uma excelente solução para você.

onerror para o Resgate

onerror pode facilmente substituir o src na tag <img> por uma imagem padrão quando ocorre um erro de carregamento:

<img src="imagem.jpg" onerror="this.onerror=null;this.src='padrão.png';" alt="descrição" />

Adicionar uma verificação extra em onerror evitará um loop infinito de carregamento de uma imagem instável.

Visualização

Imagine o elemento HTML como uma foto em uma moldura:

Moldura 🖼️: |______|

Aqui está nossa moldura sem a imagem perfeita (src):

<img src="noitedestrelada.jpg" onerror="this.src='moldura_vazia.jpg';" />

Neste caso, sempre há uma imagem de fallback atrás da moldura:

Moldura 🖼️: |🌌 (noitedestrelada.jpg)|
           |🖼️ (moldura_vazia.jpg) — apenas por precaução|

Isso garante a continuidade do design da parede (página web), ocultando invisivelmente a ausência da obra principal.

Recursos Úteis

Video

Navigation