Progress Bar

1.0.0

O componente Progress Bar nos permite mostrar o progresso de uma tarefa.

import React from "react";
import { ProgressBar } from "@nimbus-ds/components";

const Example: React.FC = () => <ProgressBar appearance="primary" value={50} />;

export default Example;

Progress Bar

Definição

O componente Progress Bar mostra visualmente o estado de progresso de uma tarefa em andamento ou processo. Serve para informar ao usuário a porcentagem concluída, reforçar a percepção de controle e estabelecer expectativas de duração, carregamento ou nível de completude. Seu uso é fundamental para manter a atenção e confiança do usuário em operações que requerem espera ativa ou passiva.

Quando usar

Para indicar o progresso de uma operação como carregamento de arquivos, sincronização, instalação, etc.
Em processos longos onde se deve informar ao usuário o estado para evitar incerteza.
Em fluxos de várias etapas ou tarefas que requerem confirmação de progresso antes de continuar.
Como indicador de completude de atributos, como por exemplo quanto crédito ou orçamento o usuário utilizou em relação ao total disponível.

Quando não usar

Quando a operação é instantânea ou quase imperceptível (menos de 1 segundo).
Se não for possível medir o progresso real (usar nesse caso um spinner ou feedback genérico).
Para mostrar sucesso ou erro final (usar um toast ou mensagem de estado complementar).

Critérios de produtividade e usabilidade

Feedback instantâneo e visível: reforça a percepção de resposta do sistema.
Evita telas de confirmação desnecessárias: o progresso é mostrado inline, mantendo o fluxo do usuário.
Reduz fricção: torna explícita a duração estimada ou o estado de completude e minimiza a incerteza.
Permite multitarefa: o usuário pode continuar outras ações enquanto observa o progresso.

Acessibilidade

Usar atributos aria-valuenow, aria-valuemin, aria-valuemax, aria-label.
Permitir que o componente seja lido por leitores de tela.
Garantir que o progresso seja compreensível sem depender apenas da cor.

Anatomia

O componente pode incluir:

Track: fundo que indica a base do progresso.
Bar: linha de progresso, cor variável conforme contexto.
Label (opcional): texto indicando a porcentagem ou estado (ex. "Carregando…").

Dependências

#Text (opcional para labels)
#Color tokens do sistema (success, warning, danger, primary, neutral)

Variantes

Default: cor neutra, para carregamentos gerais.
Primary: usado para fluxos principais do negócio.
Success: para indicar que o progresso está correto.
Warning: quando há risco ou atraso.
Danger: para erros ou processos com falha.
AI Interactive: versão animada e interativa para fluxos com IA.

Do and Don'ts

✅ Do

Mostrar valores quando estiverem disponíveis.
Usar variantes de cor conforme o contexto de sucesso, erro ou advertência.

❌ Don't

Não usar se não conseguir estimar o progresso.
Não confiar apenas na cor para comunicar o estado.
Não usar múltiplas barras de progresso ao mesmo tempo sem hierarquia visual.

Implementação

Instale o componente via terminal.

npm install @nimbus-ds/progress-bar

Props

Additional props are passed to the <ProgressBar> element. See div docs for a list of props accepted by the <ProgressBar> element.

ProgressBar

Name	Type	Default	Description
value*	number		Progress value from 0 to 100
appearance	'ai-generative' 'danger' 'neutral' 'primary' 'success' 'warning'	'neutral'	Change the visual style of the progress bar.

ProgressBar.Skeleton

Name	Type	Description
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.
width	string	Width of the skeleton. Useful when the skeleton is inside an inline element with no width of its own.
data-testid	string	This is an attribute used to identify a DOM node for testing purposes.