Progress Bar
Muestra el avance de una tarea medible como una barra que se llena de 0 a 100.
- Informar el avance de una operación medible: mostrar qué porcentaje de una tarea con duración estimable ya se completó. Ej.: subir un archivo, importar un CSV o generar un reporte.
- Reflejar el avance dentro de un flujo de varios pasos: ubicar al usuario dentro de un cuestionario o wizard, sin necesidad de que la barra represente tiempo real. Ej.: un cuestionario de configuración inicial.
- Mostrar un nivel de uso respecto de un total: indicar cuánto de un cupo, crédito o plan ya se consumió. Ej.: el uso de un límite de mensajes de un asistente de IA.
- Comunicar una operación instantánea o casi imperceptible (menos de 1 segundo): la barra no llega a leerse y solo agrega ruido visual. En su lugar, no mostrar ningún indicador o resolver la acción directamente.
- Indicar que el sistema está trabajando sin un valor de avance real: cuando no hay ningún porcentaje medible que mostrar, ni siquiera aproximado. En su lugar, usar Spinner.
- Comunicar el resultado final de una operación: un éxito, un error o una advertencia posterior al proceso. En su lugar, usar Toast o un mensaje de estado complementario.
- Guiar la navegación entre pasos: cuando además de mostrar el avance se necesita retroceder, saltear pasos o ver el detalle de cada etapa con controles propios. En su lugar, usar Stepper.
Track + Fill
- Track: superficie de fondo que representa el 100% de la tarea; usa el color backgroundColor (por defecto, neutral-surfaceDisabled).
- Fill: porción que avanza según value, pintada con el color de la appearance elegida; su ancho es proporcional al porcentaje completado.
Neutral (valor por defecto): usar en procesos estándar, secundarios o flujos que no impactan directamente el negocio y no tienen connotación de riesgo ni de logro. Ej.: la carga de una vista secundaria o el avance de un cuestionario de configuración.
Primary: reservar para procesos críticos, flujos principales del negocio o tareas en segundo plano de alto impacto que el usuario necesita monitorear de cerca. Ej.: la importación o exportación masiva de un catálogo, o el procesamiento de una orden de pago.
Success: evitar durante el avance continuo de un proceso; usar solo cuando la tarea terminó con éxito al 100%, para dar un cierre visual, o en barras que miden una meta. Ej.: una carga de archivos que llegó a destino, o el cumplimiento de una meta de ventas.
Warning: usar en barras de estado o consumo (métricas de capacidad) cuando el volumen alcanza un umbral de riesgo, como el 80%, que requiere atención preventiva. Ej.: el uso de almacenamiento en la nube o el consumo de tokens de un plan cerca de agotarse.
Danger: usar en procesos temporales cuando la tarea se detuvo por un fallo, o en barras de consumo cuando se alcanzó o superó el 100% de la capacidad permitida. Ej.: un fallo crítico al subir un archivo, o el consumo de mensajes de un plan de IA que llegó al tope.
AI generative (ai-generative): reservar para procesos de inteligencia artificial o de Lumi que tienen un avance medible, para distinguirlos visualmente de los procesos comunes. Ej.: la generación de un lote de imágenes de producto con IA, mostrando cuántas se completaron sobre el total.
Default (0.5rem): usar en la mayoría de los contextos, donde la barra acompaña otro contenido sin competir por atención.
Reducida (0.25rem): usar en contextos muy densos, como un indicador angosto de cupo dentro de un chat o una barra de estado secundaria.
El Progress Bar acompaña procesos con avance medible dentro de una card, un modal o una fila de una lista: junto a un archivo que se está subiendo, dentro de un cuestionario de configuración, o al lado de un indicador de cupo o crédito consumido.
catalogo-productos.csv
65% completado
Importando productos
40%
Acompañar la barra con un texto que indique el porcentaje o el estado, cuando el dato esté disponible.
Evitar dejar la barra sola, sin ningún texto que explique qué proceso está representando.
imagen-1.jpg
imagen-2.jpg
Usar múltiples barras de progreso en una lista solo cuando cada una tiene su propio contexto claro (por ejemplo, un archivo por fila).
Evitar apilar varias barras sin jerarquía ni contexto individual: el usuario no puede distinguir a qué corresponde cada una.
Eliminando producto en 2 s
Usar danger en una cuenta regresiva previa a una acción destructiva (por ejemplo, eliminar un producto), para reforzar visualmente que la acción está a punto de confirmarse.
Eliminando producto en 2 s
Evitar una appearance neutral o primary para comunicar una cuenta regresiva destructiva: sin el color de alerta, el usuario no percibe que la acción es irreversible.
- Rol y valores expuestos a lectores de pantalla: el componente renderiza role="progressbar" con aria-valuenow, aria-valuemin={0} y aria-valuemax={100}, para que el avance se anuncie de forma programática.
- Etiqueta accesible a cargo de quien lo usa: como el componente no incluye un label propio, hay que asociarlo con el texto que describe la tarea (por ejemplo, con aria-labelledby apuntando al Text que la nombra) para que el contexto no dependa solo del Box visual.
- Color no como única señal: además de la appearance, acompañar con el porcentaje en texto o con un ícono, para que el estado (por ejemplo, un límite alcanzado en danger) se entienda incluso sin distinguir el color.
Instalá el componente vía terminal.
npm install @nimbus-ds/componentsimport React from "react";
import { ProgressBar } from "@nimbus-ds/components";
const Example: React.FC = () => <ProgressBar appearance="neutral" value={50} />;
export default Example;Las propiedades adicionales se pasan al elemento <ProgressBar>. Consultá la documentación del elemento div para ver la lista de atributos aceptados.
ProgressBar
| Name | Type | Default | Description |
|---|---|---|---|
value* | number | Progress value from 0 to 100 | |
appearance | 'ai-generative' | 'neutral' | Change the visual style of the progress bar. |
boxShadow | '0' | '0' | Applies a box shadow to the progress bar fill using the appearance color. |
height | string | '0.5rem' | Custom height for the progress bar. Any valid CSS height value. |
backgroundColor | 'neutral-background' | 'neutral-surfaceDisabled' | Change the background color of the progress bar track. |
ProgressBar.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. | |
data-testid | string | This is an attribute used to identify a DOM node for testing purposes. |
Ayudanos a mejorar la documentación
¿Encontraste un problema o tenés una sugerencia? Contanos.