File uploader
Permite cargar un archivo o una imagen arrastrándolo o seleccionándolo desde el explorador del sistema.
- Cargar la imagen de un producto: recibir un archivo de imagen que después se muestra en el catálogo o en la tienda. Ej.: "Cargar imagen de producto".
- Adjuntar un comprobante o un archivo de respaldo: enviar un documento que respalda una operación, como un comprobante de pago o una factura.
- Habilitar arrastrar y soltar en un panel de chat conversacional: superponer una zona de carga invisible (asOverlay + FileUploader.Overlay) sobre el panel de conversación para que la persona pueda arrastrar una imagen directamente sobre el chat, sin un botón de carga visible. Ej.: adjuntar una imagen en una conversación con Lumi.
- Mostrar una imagen ya cargada sin permitir reemplazarla: el File uploader es un control de carga, no un visor de imágenes. En su lugar, usar Thumbnail.
- Elegir un valor de una lista cerrada de opciones: cuando no se trata de recibir un archivo sino de seleccionar un dato entre varios predefinidos. En su lugar, usar Select.
- Recibir texto libre: cuando el dato a capturar es texto y no un archivo. En su lugar, usar Input o Textarea.
- Icon: ícono fijo (PlusCircleIcon) que identifica el área como una zona de carga; no se configura por prop.
- Placeholder (opcional): texto que indica qué archivo cargar, ubicado según flexDirection. Si no se pasa placeholder, el área solo muestra el ícono.
- Container: superficie con borde punteado, fondo y radio que delimita el área interactiva; cambia de color según el estado (rest, active al arrastrar, disabled).
Base
1/1 (cuadrada): proporción por defecto, para imágenes que se muestran como miniatura. Ej.: la imagen principal de una variante de producto.
Horizontales
4/3: para imágenes con una orientación horizontal moderada.
16/9: para imágenes más alargadas en horizontal, como una historia o un banner ancho.
2/1: para piezas muy panorámicas.
Verticales
3/4: para imágenes con una orientación vertical moderada.
9/16: para imágenes más alargadas en vertical, como una historia.
1/2: para piezas muy angostas y alargadas en vertical.
column (default): ícono arriba y label abajo, centrados. Usar en áreas más cuadradas o altas.
row: ícono y label en línea. Usar en franjas angostas y horizontales, como un campo de formulario. Ej.: adjuntar un comprobante dentro de un formulario.
Default: toda el área abre el explorador de archivos al hacer clic, además de aceptar arrastrar y soltar.
Overlay (asOverlay + FileUploader.Overlay): zona de carga transparente que se superpone a un contenido ya existente (ej. una conversación o una imagen ya cargada) y solo se visualiza cuando se arrastra un archivo nuevo encima. La aplicación actualiza el contenido mostrado a partir de onDrop/onDropSuccess.
El File uploader aparece dentro de una card de edición, debajo del título de la sección a la que pertenece (por ejemplo, "Fotos y video" en la edición de un producto), ocupando el ancho disponible de la card.
Fotos y video
Tamaño mínimo recomendado: 1280px
Acompañar el área de carga con el formato y el tamaño de archivo aceptado.
Evitar dejar el área de carga sin ninguna referencia del archivo esperado.
Elegir la proporción de la imagen a cargar según el lugar donde se va a mostrar.
Evitar forzar una proporción distinta a la del lugar donde se muestra la imagen: genera recortes o distorsión.
Mostrar un mensaje de error claro cuando el archivo no cumple el formato aceptado.
Evitar dejar el intento de carga sin feedback cuando el archivo no se pudo subir.
- Label visible como texto, no solo como ícono: el placeholder describe con texto qué archivo cargar; el ícono por sí solo no comunica la acción.
- Tipos de archivo restringidos con accept: limitar accept a los formatos que la operación soporta evita que la persona intente cargar un archivo que después va a ser rechazado.
- Errores de validación comunicados por la aplicación: el componente no muestra un mensaje de error propio ante un archivo rechazado; onDropReject y onError devuelven el motivo, y quien lo implementa debe mostrarlo cerca del área de carga (por ejemplo, con un texto o un Alert).
- Estado deshabilitado: el atributo disabled bloquea tanto el clic como el arrastre, y atenúa el área para que se lea como no disponible.
Instalá el componente vía 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;Las propiedades adicionales se pasan al elemento <FileUploader>. Consultá la documentación del elemento input para ver la lista de atributos aceptados.
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 |
Ayudanos a mejorar la documentación
¿Encontraste un problema o tenés una sugerencia? Contanos.