# Progress

Barra de progresso de tarefa com fim conhecido: enviar arquivo, gerar relatório.

Sem `value` ela vira indeterminada; nesse caso prefira o `Spinner`, que ocupa
menos e não promete um fim que ninguém sabe medir.

`format` escreve o número do `showValue`: o nome de um formatador da casa, ou
uma função sua.

## Movimento

A barra enche do zero na montagem, pela escala horizontal a partir da esquerda (`animate-fill`, `--rc-duration-slow`), e depois anda até cada valor novo pela largura. O indeterminado troca a entrada pelo vaivem dele. Com "reduzir movimento", a barra nasce no valor.

## Quando não usar

Para quanto de uma capacidade está em uso (espaço em disco, cota de notas do
mês, limite de crédito), use `Meter`. A diferença não é de aparência, é do que
o número faz: o progresso anda para o fim e termina, a medida fica parada e pode
subir e descer.

Trocar um pelo outro chega ao leitor de tela: a barra de progresso é anunciada
como algo que carrega, e "carregando 72%" para um disco que não está carregando
nada faz quem ouve esperar por um fim que nunca vem.

## No React Native

Traduz: o `@rivocode/ui-native` exporta `Progress` - `value` de 0 a 100 e `label`; sem `format`; a barra anda até o valor novo. A API não é a mesma do web (no nativo tudo é controlado), e a [tabela de paridade](/react-native) diz o que muda peça a peça.

## Importação

```tsx
import { Progress } from '@rivocode/ui'
```

## Exemplos

### Com rótulo

```tsx
import { Progress } from '@rivocode/ui'

export function WithLabel() {
  return (
    <div className="flex w-80 flex-col gap-6">
      <Progress value={62} label="Enviando notas" showValue />
      <Progress value={100} label="Concluido" showValue />
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Desde | O que faz |
| --- | --- | --- | --- | --- |
| `value` | `number \| null` | sim | 0.4.0 | The current value. |
| `aria-valuetext` | `string` |  | 0.4.0 | A string value that provides a user-friendly name for `aria-valuenow`, the current value of the progress bar. |
| `classNames` | `Partial<Record<"indicator" \| "label" \| "track" \| "value", string>>` |  | 0.5.0 | Classe por parte: `label`, `value`, `track`, `indicator`. |
| `format` | `Format` |  | 0.4.0 | Como o numero e escrito: nome de formatador da casa (`percent`, `currencyShort`, `integer`...) ou funcao propria. |
| `getAriaValueText` | `((formattedValue: string, value: number \| null) => string)` |  | 0.4.0 | Accepts a function which returns a string value that provides a human-readable text alternative for the current value of the progress bar. |
| `label` | `ReactNode` |  | 0.4.0 | Texto acima da barra. |
| `locale` | `LocalesArgument` |  | 0.4.0 | The locale used by `Intl.NumberFormat` when formatting the value. |
| `max` | `number` |  | 0.4.0 | The maximum value. |
| `min` | `number` |  | 0.4.0 | The minimum value. |
| `numberFormat` | `NumberFormatOptions` |  | 0.5.0 | As opcoes do `Intl.NumberFormat`, para quem precisa delas. |
| `render` | `ComponentRenderFn<HTMLProps, ProgressRootState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | 0.4.0 | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |
| `showValue` | `boolean` |  | 0.4.0 | Mostra a porcentagem ao lado do rotulo. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [Alert](/componentes/alert.md)
- [Badge](/componentes/badge.md)
- [EmptyState](/componentes/empty-state.md)
- [Indicator](/componentes/indicator.md)
- [Kbd](/componentes/kbd.md)
- [Meter](/componentes/meter.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)