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).

Propiedades y configuraciones

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: 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.

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.