File uploader
Permite carregar um arquivo ou uma imagem arrastando-o ou selecionando-o pelo explorador de arquivos do sistema.
- Carregar a imagem de um produto: receber um arquivo de imagem que depois é exibido no catálogo ou na loja. Ex.: "Carregar imagem do produto".
- Anexar um comprovante ou um arquivo de apoio: enviar um documento que respalda uma operação, como um comprovante de pagamento ou uma nota fiscal.
- Habilitar arrastar e soltar em um painel de chat conversacional: sobrepor uma zona de carregamento invisível (asOverlay + FileUploader.Overlay) sobre o painel de conversa para que a pessoa possa arrastar uma imagem diretamente sobre o chat, sem um botão de carregamento visível. Ex.: anexar uma imagem em uma conversa com a Lumi.
- Exibir uma imagem já carregada sem permitir substituí-la: o File uploader é um controle de carregamento, não um visualizador de imagens. Usar Thumbnail nesse caso.
- Escolher um valor de uma lista fechada de opções: quando não se trata de receber um arquivo, mas de selecionar um dado entre vários predefinidos. Usar Select nesse caso.
- Receber texto livre: quando o dado a capturar é texto e não um arquivo. Usar Input ou Textarea nesse caso.
- Icon: ícone fixo (PlusCircleIcon) que identifica a área como uma zona de carregamento; não é configurado por prop.
- Placeholder (opcional): texto que indica qual arquivo carregar, posicionado de acordo com flexDirection. Se placeholder não for informado, a área exibe apenas o ícone.
- Container: superfície com borda pontilhada, fundo e raio que delimita a área interativa; muda de cor de acordo com o estado (rest, active ao arrastar, disabled).
Base
1/1 (quadrada): proporção padrão, para imagens exibidas como miniatura. Ex.: a imagem principal de uma variante de produto.
Horizontais
4/3: para imagens com uma orientação horizontal moderada.
16/9: para imagens mais alongadas na horizontal, como um story ou um banner largo.
2/1: para peças bem panorâmicas.
Verticais
3/4: para imagens com uma orientação vertical moderada.
9/16: para imagens mais alongadas na vertical, como um story.
1/2: para peças bem estreitas e alongadas na vertical.
column (default): ícone acima e label abaixo, centralizados. Usar em áreas mais quadradas ou altas.
row: ícone e label em linha. Usar em faixas estreitas e horizontais, como um campo de formulário. Ex.: anexar um comprovante dentro de um formulário.
Default: toda a área abre o explorador de arquivos ao clicar, além de aceitar arrastar e soltar.
Overlay (asOverlay + FileUploader.Overlay): zona de carregamento transparente que se sobrepõe a um conteúdo já existente (ex. uma conversa ou uma imagem já carregada) e só é exibida quando um novo arquivo é arrastado sobre ela. A aplicação atualiza o conteúdo exibido a partir de onDrop/onDropSuccess.
O File uploader aparece dentro de um card de edição, abaixo do título da seção à qual pertence (por exemplo, "Fotos e vídeo" na edição de um produto), ocupando a largura disponível do card.
Fotos e vídeo
Tamanho mínimo recomendado: 1280px
Acompanhar a área de carregamento com o formato e o tamanho de arquivo aceitos.
Evitar deixar a área de carregamento sem nenhuma referência do arquivo esperado.
Escolher a proporção da imagem a carregar de acordo com o local onde ela será exibida.
Evitar forçar uma proporção diferente da usada no local onde a imagem é exibida: gera cortes ou distorção.
Exibir uma mensagem de erro clara quando o arquivo não atende ao formato aceito.
Evitar deixar a tentativa de carregamento sem feedback quando o arquivo não pôde ser enviado.
- Label visível como texto, não apenas como ícone: o placeholder descreve em texto qual arquivo carregar; o ícone por si só não comunica a ação.
- Tipos de arquivo restritos com accept: limitar accept aos formatos que a operação suporta evita que a pessoa tente carregar um arquivo que depois será rejeitado.
- Erros de validação comunicados pela aplicação: o componente não exibe uma mensagem de erro própria para um arquivo rejeitado; onDropReject e onError retornam o motivo, e quem implementa deve exibi-lo perto da área de carregamento (por exemplo, com um texto ou um Alert).
- Estado desabilitado: o atributo disabled bloqueia tanto o clique quanto o arrasto, e atenua a área para que seja lida como indisponível.
Instalar o componente via terminal.
npm install @nimbus-ds/componentsimport React from "react";
import { FileUploader } from "@nimbus-ds/components";
const Example: React.FC = () => (
<FileUploader placeholder="Cargar imagen" width="104px" />
);
export default Example;As propriedades adicionais são passadas para o elemento <FileUploader>. Consulte a documentação do elemento input para ver a lista de atributos aceitos.
FileUploader
| Name | Type | Default | Description |
|---|---|---|---|
placeholder | string | Provide additional context to the action. | |
accept | string | 'image/jpeg,image/gif,image/png' | Accept file types |
height | string | '100%' | Height value of the file uploader. Defaults to 100%. |
width | string | '100%' | Width value of the file uploader. Defaults to 100%. |
aspectRatio | '1/1' | '1/1' | Permitted aspect ratios for the size of the file uploader. |
flexDirection | 'column' | 'column' | Defines the position of the placeholder in relation to the icon. |
onDrop | object | Callback fired when files are dropped (before validation) | |
onDropReject | object | Callback fired when all dropped files are rejected due to file type validation | |
onDropSuccess | object | Callback fired when files are successfully accepted and processed | |
onError | object | Callback fired when an error occurs during file drop processing | |
children | React.ReactNode | Content to render inside the file uploader container | |
dragOverlay | React.ReactNode | Custom overlay element to render when dragging files over the uploader. When defined, this overlay will be displayed instead of children during drag operations. | |
disableClickUpload | boolean | 'false' | When true, the file uploader will not be clickable and files can only be uploaded by dragging and dropping. Useful for invisible upload areas used along FileUploader.Overlay. |
asOverlay | boolean | 'false' | When true, the file uploader will be rendered as an overlay. Useful for invisible upload areas used along FileUploader.Overlay. |
FileUploader.Skeleton
| Name | Type | Default | Description |
|---|---|---|---|
width | string | Width of the skeleton. Useful when the skeleton is inside an inline element with no width of its own. | |
className | string | ||
height | string | Height of the skeleton. Useful when you don't want to adapt the skeleton to a text element but for instance a card. | |
aspectRatio | '1/1' | '1/1' | Permitted aspect ratios for the size of the file uploader. |
data-testid | string | This is an attribute used to identify a DOM node for testing purposes. |
FileUploader.Overlay
| Name | Type | Default | Description |
|---|---|---|---|
title | string | Title text displayed in the overlay | |
subtitle | string | Subtitle text displayed below the title | |
imageSrc | string | Source URL for the image displayed in the overlay | |
imageAlt | string | Alt text for the image | |
borderColor | 'ai-generativeInteractiveHover' | 'primary-interactive' | Border color of the overlay |
backgroundColor | 'neutral-background' | 'primary-surface' | Background color of the overlay |
borderRadius | '0-5' | '2' | Border radius of the overlay |
children | React.ReactNode | Content to render inside the overlay |
Ajude-nos a melhorar a documentação
Encontrou um problema ou tem uma sugestão? Conte para a gente.