Image
Substituto direto de `<img>` que reserva espaço fixo via `ratio` e `size`, com skeleton de carregamento e fallback automático quando a imagem não existe ou falha.
O mk-image funciona como substituto direto de <img>, controlando as dimensões via ratio (proporção) e size (escala), preenchido pela imagem conforme fit. Enquanto a imagem carrega, exibe um skeleton; se não houver src ou a imagem falhar ao carregar, exibe um fallback com ícone. Use em thumbnails, banners, hero images, conteúdo de artigo e avatares de entidades não-pessoa.
Padrão
import { MkImage } from '@db1/makuco-ui-react';
<MkImage src="https://picsum.photos/id/1015/800/800" alt="Foto de exemplo" /><mk-image src="https://picsum.photos/id/1015/800/800" alt="Foto de exemplo"></mk-image>Proporções
Cinco proporções via ratio: 1:1 (padrão), 16:9, 4:3, 3:4 e 9:16. Cada combinação de ratio × size resolve para uma dimensão fixa em pixels, evitando layout shift.
<MkImage src="/foto.jpg" ratio="16:9" size="lg" alt="Banner" /><mk-image src="/foto.jpg" ratio="16:9" size="lg" alt="Banner"></mk-image>Tamanhos
Cinco escalas fixas via size: xs, sm, md (padrão), lg e xl.
<MkImage src="/foto.jpg" size="lg" alt="Foto" /><mk-image src="/foto.jpg" size="lg" alt="Foto"></mk-image>Tamanho automático
Use size="auto" para respeitar apenas o ratio, sem limitar a caixa a uma dimensão fixa. A imagem ocupa 100% da largura do contêiner pai e a altura é resolvida via aspect-ratio — útil em layouts fluidos (cards, grids responsivos) onde a largura disponível varia.
<MkImage src="/banner.jpg" ratio="16:9" size="auto" alt="Banner responsivo" /><mk-image src="/banner.jpg" ratio="16:9" size="auto" alt="Banner responsivo"></mk-image>Preenchimento (fit)
A prop fit equivale a object-fit: cover (padrão) recorta mantendo proporção, contain encaixa sem recortar, fill estica para preencher a caixa (pode distorcer).
<MkImage src="/foto.jpg" fit="contain" alt="Foto" /><mk-image src="/foto.jpg" fit="contain" alt="Foto"></mk-image>Arredondamento
Use radius para arredondar os cantos da imagem. Os valores seguem a escala de border-radius do sistema: 2xs, xs, sm, md, lg, xl, 2xl, 3xl e full. Quando ausente, a imagem não tem arredondamento.
<MkImage src="/foto.jpg" size="sm" radius="lg" alt="Foto arredondada" /><mk-image src="/foto.jpg" size="sm" radius="lg" alt="Foto arredondada"></mk-image>Borda
Use stroke para adicionar uma borda ao redor da imagem. subtle aplica a borda com baixo contraste (uso geral), strong com alto contraste (destaque ou seleção). Quando ausente, nenhuma borda é exibida.
<MkImage src="/foto.jpg" size="sm" stroke="subtle" alt="Foto com borda" /><mk-image src="/foto.jpg" size="sm" stroke="subtle" alt="Foto com borda"></mk-image>Fallback
Quando src não é definido, ou quando a imagem falha ao carregar, mk-image exibe um fallback fixo (ícone genérico em uma box com borda tracejada) — sem passar pelo estado de skeleton.
<MkImage alt="Sem imagem" /><mk-image alt="Sem imagem"></mk-image>Props
| Prop | Tipo | Padrão | Descrição |
|---|---|---|---|
src | string | — | URL da imagem. Quando ausente, exibe o fallback imediatamente. |
alt | string | "" | Texto alternativo, repassado ao <img> interno e usado como aria-label do host quando preenchido. |
ratio | "1:1" | "16:9" | "4:3" | "3:4" | "9:16" | "1:1" | Proporção da caixa de imagem. Reflete como atributo do host. |
size | "xs" | "sm" | "md" | "lg" | "xl" | "auto" | "md" | Escala de tamanho, combinada com ratio para definir width/height fixos. Com "auto", ocupa 100% da largura do contêiner pai e resolve a altura via aspect-ratio, sem dimensão fixa. Reflete como atributo do host. |
fit | "cover" | "contain" | "fill" | "cover" | Equivalente a object-fit do <img> interno. |
loading | "lazy" | "eager" | "lazy" | Repassado ao atributo nativo loading do <img>. |
radius | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "full" | — | Arredondamento dos cantos da imagem. Quando ausente, não aplica border-radius. |
stroke | "subtle" | "strong" | — | Borda ao redor da imagem. subtle usa baixo contraste, strong usa alto contraste. Quando ausente, nenhuma borda é exibida. |
Eventos
| Evento | Payload | Descrição |
|---|---|---|
mkLoad | CustomEvent<void> | Emitido quando o <img> interno dispara load com sucesso. |
mkError | CustomEvent<void> | Emitido quando o <img> interno dispara error (URL inválida, 404, falha de rede). |
Acessibilidade
- Quando
altestá preenchido, o host receberole="img"earia-label={alt}— anunciado independentemente do estado (loading/loaded/fallback). - Quando
altestá vazio, o host não receberolenemaria-label— comportamento decorativo. - O ícone do fallback tem
aria-hidden="true". - Não é focável e não responde a clique ou teclado — mesmo comportamento de um
<img>semtabindex. - Contraste do fallback (borda e ícone) ≥ 3:1 em ambos os temas, via tokens
--stroke-subtlee--icon-low-emphasis.
Illustration Icon
Ícone dentro de um container com fundo tonal, usado em empty states, cards de destaque, onboarding e listagens para reforçar o significado semântico de uma cor.
Quick View
Exibe um conjunto de imagens do mesmo produto — imagem em foco com setas e miniaturas, e um overlay interno para ampliar cada imagem sem sair da página.