Thumbnail
Permite exibir a miniatura de uma imagem, com um placeholder automático quando a imagem não está disponível.
- Exibir a imagem de um produto: representar de forma compacta a foto principal de um produto em uma listagem, uma tabela ou um seletor de variantes. Ex.: a miniatura de cada linha em uma listagem de produtos.
- Exibir o conteúdo de uma galeria: apresentar um conjunto de imagens ou arquivos de mídia de forma uniforme, respeitando uma proporção fixa por célula. Ex.: a galeria de fotos de um produto.
- Referenciar um pedido ou um arquivo com imagem: dar contexto visual rápido a um item que tem uma imagem associada, sem que a imagem seja o foco principal da tela. Ex.: a miniatura do produto no detalhe de um pedido.
- Representar a imagem principal de uma tela: quando a imagem precisa de protagonismo (banner, capa, imagem destacada). Usar, em vez disso, a tag <img> nativa ou um componente de layout próprio com o tamanho que o caso exigir.
- Sobrepor uma ação à miniatura: quando, além de exibir a imagem, é necessária uma ação sobre ela, como um ícone de excluir ou um checkbox de seleção em um canto. Usar, em vez disso, Thumbnail with action.
- Permitir enviar ou substituir uma imagem: quando o objetivo é capturar um arquivo do usuário, não apenas exibi-lo. Usar, em vez disso, File uploader.
Com imagem
Sem imagem (placeholder automático)
- Container: superfície com bordas arredondadas que recorta e contém a imagem ou o placeholder, com o tamanho e a proporção definidos por width e aspectRatio.
- Icon: quando src não é informado, o componente renderiza automaticamente este ícone de câmera dentro do Container, como placeholder; não exige nenhuma prop adicional.
1/1 (default): proporção quadrada, a mais frequente em listagens e galerias de produto. Ex.: a miniatura de um produto em uma tabela.
4/3: proporção retangular horizontal, para imagens com mais largura do que altura. Ex.: a foto de um ambiente ou de uma loja física.
3/4: proporção retangular vertical, para imagens com mais altura do que largura. Ex.: a foto de uma peça de roupa.
16/9: proporção wide horizontal, para conteúdo do tipo vídeo ou capa. Ex.: a miniatura de um vídeo de produto.
9/16: proporção wide vertical, para conteúdo do tipo story ou vídeo vertical. Ex.: a miniatura de um vídeo gravado a partir de um celular.
2/1: proporção extra wide horizontal, para imagens muito panorâmicas. Ex.: a capa de uma coleção.
1/2: proporção extra wide vertical, para imagens muito alongadas. Ex.: um banner lateral estreito.
Largura fixa (ex. 72px): valor recomendado em listagens e tabelas, onde o tamanho se repete em cada linha. Ex.: a miniatura de produto em uma listagem.
100% (default): ocupa toda a largura do contêiner que o envolve. Ex.: cada célula de uma grade de galeria com colunas de largura variável.
O Thumbnail aparece junto ao nome ou ao identificador principal de um item, em contextos em que esse item tem uma imagem associada: linhas de listagens de produtos, tabelas de pedidos, seletores de variantes e células de uma galeria. Quando o item não tem imagem, o próprio componente substitui a imagem pelo placeholder de câmera, sem que o contexto ao redor precise mudar.
Deixar que o componente exiba seu placeholder automático quando o produto não tem imagem.
Evitar montar um placeholder próprio em vez do que o componente já fornece.
Manter a mesma proporção (aspectRatio) em todas as miniaturas de uma mesma listagem ou galeria.
Evitar misturar proporções diferentes dentro da mesma listagem ou galeria: quebra a grade visual.
- Texto alternativo obrigatório: alt é uma prop obrigatória; deve descrever o conteúdo da imagem, sem repetir "imagem" ou "foto". Ex.: alt="Tênis esportivo azul", não alt="imagem".
- Placeholder sem dependência de cor: quando não há imagem, o ícone de câmera comunica a ausência de conteúdo pela própria forma, sem depender apenas de uma cor ou de um fundo diferente para transmitir o estado.
- Recorte acessível do conteúdo: a imagem é recortada com object-fit: cover dentro do Container; por isso, convém usar imagens centradas no sujeito principal, para que o recorte não oculte a parte relevante.
Instale o componente via terminal.
npm install @nimbus-ds/componentsimport React from "react";
import { Thumbnail } from "@nimbus-ds/components";
import { SHOES_IMAGE_URL } from "../../../lib/mocks/mock-images";
const Example: React.FC = () => (
<Thumbnail
src={SHOES_IMAGE_URL}
alt="Sports sneakers"
width="104px"
/>
);
export default Example;As propriedades adicionais são passadas para o elemento <Thumbnail>. Consulte a documentação do elemento img para ver a lista de atributos aceitos.
- File uploader — Para permitir que o usuário envie ou substitua uma imagem ou um arquivo, em vez de apenas exibi-la.
- Thumbnail with action — Para sobrepor uma ação (ícone, checkbox) em um canto da miniatura.
Thumbnail
| Name | Type | Default | Description |
|---|---|---|---|
alt* | string | The required alt attribute specifies an alternate text for an image, if the image cannot be displayed. | |
children | React.ReactNode | The content of the thumbnail. | |
aspectRatio | '1/1' | '1/1' | Permitted aspect ratios for the size of the thumbnail image. |
width | string | '100%' | Width value of the thumbnail image. Defaults to 100%. |
Thumbnail.Skeleton
| Name | Type | Default | Description |
|---|---|---|---|
aspectRatio | '1/1' | '1/1' | Permitted aspect ratios for the size of the thumbnail image. |
width | string | Width of the skeleton. Useful when the skeleton is inside an inline element with no width of its own. | |
className | string | ||
data-testid | string | This is an attribute used to identify a DOM node for testing purposes. |
Ajude-nos a melhorar a documentação
Encontrou um problema ou tem uma sugestão? Conte para a gente.