Todos los componentes (204)

Progreso

Superficies · Progress

Qué es y cuándo usarlo

Barra de progreso de una tarea que avanza y acaba: subir un fichero, importar clientes, procesar un pedido. Con indeterminate cuando no se sabe cuánto falta.

Cuándo usarlo

Tareas con final: value va de minValue a maxValue (0 y 100 por defecto).
withPercent escribe el avance al lado, con el formato del idioma («42 %»); formatOptions o valueLabel («3 de 7») si no vale el porcentaje.
indeterminate cuando no hay forma de saber cuánto queda: una barra que va y viene, nunca un porcentaje inventado.
hiddenLabel cuando el texto de al lado ya dice lo que avanza: se sigue llamando igual para quien no ve la barra, pero no se pinta dos veces.
tone para el color de la barra (success al acabar, error si ha fallado); el color no basta solo, el texto tiene que decirlo también.

Cuándo no

Un nivel que está ahí, suba o baje (espacio usado, stock): Gauge.
Lo que se lleva leído de una página: ReadingProgress.
La espera de un botón: Button con loading.
Las fases de un proceso: Steps.

Teclado: no es enfocable.

Accesibilidad: es un <div role="progressbar"> propio (el <progress> nativo no se deja vestir) con label como nombre y aria-valuenow y aria-valuetext, así que quien no ve la barra también sabe por dónde va. La etiqueta dice QUÉ avanza («Subiendo la factura»), no «Progreso». La indeterminada no lleva aria-valuenow. Con movimiento reducido la barra indeterminada no se para, va más despacio: dice que algo está pasando, no es decoración.

Aspecto fino: --amset-progress-duration, lo que tarda una ida de la barra indeterminada (dos vueltas de --amset-duration-spin, con --amset-easing-standard). Lo demás, con las clases amset-progress, amset-progress--sm (vía de 4 px en vez de 8) y amset-progress--indeterminate. El relleno es --amset-accent si no lleva tone.

Contexto: el porcentaje se escribe con el idioma de LocaleProvider (o de AmsetProvider).

Cómo se ve

<Progress label="Subiendo la factura" value={42} withPercent />
<Progress label="Importando clientes" value={310} maxValue={500} withPercent />
<Progress label="Procesando el pedido en el servidor" indeterminate />
<Progress label="Subiendo el albaran" value={62} tone="error" withPercent valueLabel="Error al subir" />

Props

Se importa con import { Progress } from '@amset/ui'. Las obligatorias van marcadas.

Prop	Tipo	Para qué sirve
`label`obligatoria	`string`	Qué está pasando. "Subiendo la factura", no "Progreso".
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	Identifies the element that provides a detailed, extended description for the object.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`className`	`string`	Se une a las clases de la biblioteca, no las sustituye.
`formatOptions`	`Intl.NumberFormatOptions`	Como se escribe el valor. Por defecto, en tanto por ciento.
`hiddenLabel`	`boolean`	La etiqueta se dice pero no se pinta: para cuando al lado ya pone lo que avanza («Subiendo, 62 %») y repetirlo debajo solo ocupa sitio.
`id`	`string`	—
`indeterminate`	`boolean`	Cuando no se sabe cuanto falta: ni `aria-valuenow` ni porcentaje escrito.
`maxValue`	`number`	—
`minValue`	`number`	—
`size`	`"sm" \| "md"`	—
`tone`	`"neutral" \| "accent" \| "secondary" \| "tertiary" \| "info" \| "success" \| "warning" \| "error"`	El color de la barra: `success` al acabar bien, `error` si ha fallado, `warning` si va con problemas. Sin tono es de acento. El color NO es lo unico que lo dice -no se puede leer con un filtro de color o un lector de pantalla-: ponlo tambien en el texto (`valueLabel`: «Error al subir»).
`value`	`number`	Lo que lleva hecho. Por defecto 0, y se recorta entre el minimo y el maximo.
`valueLabel`	`ReactNode`	El valor ya escrito, si no vale el formato automatico («3 de 7»).
`withPercent`	`boolean`	Enseña el porcentaje al lado. Con progreso indeterminado no sale.

Acepta además los atributos del elemento que pinta: className, style, data-*, aria-* y sus eventos.

En el banco de pruebas

Cada estado y cada variante, para tocarlos de uno en uno, en su ficha de ui.amset.tech: