Recomendado: Muestra el avance en procesos que toman tiempo
La barra confirma que el sistema sigue trabajando y cuánto falta, y evita que la persona recargue o abandone el trámite.
Progress
Las barras de progreso muestran cuánto avanza un proceso que toma tiempo, como subir un archivo o generar un documento. Son de solo lectura y tienen dos formas: lineal (barra con porcentaje) y circular (anillo compacto).
Anatomía del componente
Cargando anatomía…
- Contenedor
- Pista
- Barra de avance
- Etiqueta
Propiedades y configuraciones
Tipo
La barra lineal muestra el porcentaje junto al avance; la circular sirve para elementos pequeños, como un ítem de lista. Acompáñalas con un texto que diga qué se está procesando.
El aria-label nombra el proceso; en la interfaz, muéstralo también como título sobre la barra.
50 %
Variante
El modificador `--danger` marca que el proceso falló, con cualquier valor. Junto a la barra, explica qué pasó y cómo seguir, como en File Upload.
El proceso avanza o terminó sin problemas.
100 %
60 %
Cuando usarlo
Úsalo cuando un proceso tarda más de unos segundos y la aplicación conoce cuánto ha avanzado: subir documentos a una postulación, generar un certificado, procesar una declaración. La barra lineal sirve cuando hay espacio para el porcentaje; la circular, para indicar avance dentro de un elemento pequeño.
Buenas prácticas
Recomendado: Acompáñala con un texto que diga qué está pasando
El porcentaje solo no explica qué se procesa. Un título breve da contexto a la barra y ayuda a quien usa lector de pantalla.
Recomendado: En caso de error, explica qué pasó y cómo seguir
Acompaña el estado de error con un mensaje claro y una acción para continuar. La barra roja sola no dice qué hacer.
Recomendado: Usa la forma circular dentro de elementos pequeños
Cuando el avance corresponde a un ítem de una lista, el anillo indica el progreso sin desplazar el resto del contenido.
Malas prácticas
No recomendado: No la uses para indicar los pasos de un formulario
La persona necesita saber en qué paso está y cuáles vienen, no un porcentaje. Para eso existe el Stepper.
No recomendado: No muestres un avance que no es real
Una barra que se queda detenida en 99% genera desconfianza. Si no conoces el avance, no inventes un porcentaje.
No recomendado: No la uses para mostrar niveles, puntajes o cupos
La barra representa un proceso que avanza. Usada para un tramo o un puntaje, parece que algo se está cargando.
No recomendado: No muestres varios indicadores para una misma espera
Varios anillos cargando a la vez hacen difícil saber qué se espera y cuánto falta. Muestra un solo indicador para el proceso.
Recomendaciones de accesibilidad
Mantén el rol y los valores sincronizados
El componente usa role="progressbar" con aria-valuemin="0", aria-valuemax="100" y aria-valuenow. Cada vez que cambies --cl-progress-value, actualiza también aria-valuenow con el mismo número.
Dale un nombre que diga qué avanza
En los ejemplos del kit el aria-label es genérico (“Progreso”). En uso real, nómbralo según el proceso (“Subiendo cartola-ahorro.pdf”) o vincúlalo al texto visible con aria-labelledby.
No dependas solo del color para el error
El estado --danger solo cambia el color del relleno. Cambia también la etiqueta (p. ej. “Error”) y muestra un mensaje que explique qué pasó.
Anuncia el resultado, no cada punto de avance
Los lectores de pantalla no necesitan escuchar cada porcentaje. Anuncia el inicio y el final (o un error) con una región viva, como un Snackbar con role="status" o un Alert.
Da contexto a la forma circular
El anillo no tiene texto propio: acompáñalo con un texto visible (“Subiendo”) y un nombre accesible, para que no sea un indicador mudo.
Respeta la preferencia de movimiento reducido
El kit desactiva la animación del relleno con prefers-reduced-motion. Si agregas animaciones propias alrededor del indicador, aplica el mismo criterio.
Última actualización: Octubre de 2026