Image
Imagem — mostra uma foto numa moldura, com legenda opcional, um skeleton durante o carregamento e um substituto que mantém o layout quando o arquivo não carrega.
Instalação
Configure o Camaleo uma vez (Instalação) e importe o componente. Ele é um componente de cliente, porque observa o evento de erro da imagem.
import { Image } from "@camaleo/react";Anatomia
Uma <figure> enquanto a imagem funciona, e uma <div> no lugar dela quando falha. style e className vão para o elemento de fora; todas as outras props vão para a <img>.
Quando falha, o substituto padrão toma o lugar da figura inteira:
Exemplos
Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.
Legenda e crédito
caption vira uma <figcaption> que o leitor de tela liga à imagem; coloque o crédito ou o tamanho do arquivo em captionMeta.
Tamanho e corte
width e height reservam o espaço antes de o arquivo chegar; um aspectRatio no style corta a mesma foto em 16:9 ou 1:1 com object-fit: cover.
Skeleton de carregamento
Ligue loadingState enquanto espera o arquivo e desligue no onLoad; o componente não desliga sozinho.
Não foi possível carregar a foto de capa
capa-serra-da-bocaina.jpg
Quando o arquivo falha
O substituto padrão mantém a moldura e mostra o nome do arquivo. Ele recebe role="img" e o alt como nome, então o leitor de tela ainda diz o que deveria estar ali.
A foto não carregou
A conexão caiu. O arquivo continua no servidor.
Substituto com nova tentativa
Clique em Tentar de novo. Um fallback próprio pode ter controles, e recebe role="group" para eles continuarem acessíveis; depois da nova tentativa, o foco fica na caixa e uma mensagem de status confirma.
Os três estados
Alterne entre carregada, carregando e com erro. O estado de erro só é lido na montagem, então troque a key quando precisar reiniciá-lo.
Imagem decorativa
Use alt="" só quando o texto ao lado já diz tudo. O alt é vazio por padrão, então uma foto sem alt também some para o leitor de tela.
Em contexto
Imagens costumam ficar no topo de um card ou numa grade de miniaturas. São pedaços inteiros de interface para copiar, no estilo que você escolheu.
Biblioteca de mídia
3 arquivos · Campanha “Serra 2026”
Arquivo não encontrado
foto-da-equipe.jpg
Boas práticas
alt="Duas fileiras de montanhas verdes sob um céu laranja de fim de tarde"Diga o que importa neste contexto, numa frase, como você contaria para alguém ao telefone.
alt="imagem.png"O leitor de tela já diz "imagem", e "imagem.png" não conta nada sobre o conteúdo.
Dê a todas as miniaturas o mesmo aspectRatio, para as linhas se alinharem seja qual for o formato de cada foto.
A linha fica torta, e o olho segue os buracos em vez das fotos.
Props
role="group" com o nome do alt.src.<figcaption>.key para reiniciar.onLoad.loadingState aqui."", que marca a imagem como decorativa.width, o navegador reserva o espaço antes de carregar.height, o navegador reserva o espaço antes de carregar.style e className vão para a <figure> de fora ou para o substituto; um aspectRatio ou uma altura ali corta a imagem. Todos os outros atributos de <img>, como loading="lazy" ou srcSet, vão para a imagem.
Styling hooks
Mude o visual sem copiar o componente: use os slots ou defina os tokens num elemento pai, num estilo ou na própria imagem.
Atributos
Tokens que ele lê
Cor
Forma e tamanho
Só deste componente
Acessibilidade
- Carregada, ela é uma <img> dentro de uma <figure>; a legenda é uma <figcaption>.
- Dê alt a toda imagem que tem significado. Sem ele, o alt fica "" e o leitor de tela pula a imagem.
- O substituto padrão é role="img" com o nome do alt, então uma foto quebrada continua com nome. Sem alt, o nome é "Unavailable image", em inglês.
- O skeleton fica em aria-hidden e a figura não tem estado de ocupado, então uma imagem lenta não é anunciada.