Progress Bar
Mostra o avanço de uma tarefa mensurável como uma barra que se enche de 0 a 100.
- Informar o avanço de uma operação mensurável: mostrar qual porcentagem de uma tarefa com duração estimável já foi concluída. Ex.: enviar um arquivo, importar um CSV ou gerar um relatório.
- Refletir o avanço dentro de um fluxo de várias etapas: posicionar o usuário dentro de um questionário ou wizard, sem que a barra precise representar tempo real. Ex.: um questionário de configuração inicial.
- Mostrar um nível de uso em relação a um total: indicar quanto de uma cota, crédito ou plano já foi consumido. Ex.: o uso de um limite de mensagens de um assistente de IA.
- Comunicar uma operação instantânea ou quase imperceptível (menos de 1 segundo): a barra não chega a ser lida e só adiciona ruído visual. Nesse caso, não exibir nenhum indicador ou resolver a ação diretamente.
- Indicar que o sistema está trabalhando sem um valor de avanço real: quando não há nenhuma porcentagem mensurável para mostrar, nem mesmo aproximada. Usar Spinner em vez disso.
- Comunicar o resultado final de uma operação: um sucesso, um erro ou um alerta posterior ao processo. Usar Toast ou uma mensagem de estado complementar em vez disso.
- Guiar a navegação entre etapas: quando, além de mostrar o avanço, for necessário voltar, pular etapas ou ver o detalhe de cada uma com controles próprios. Usar Stepper em vez disso.
Track + Fill
- Track: superfície de fundo que representa os 100% da tarefa; usa a cor backgroundColor (por padrão, neutral-surfaceDisabled).
- Fill: porção que avança conforme value, pintada com a cor da appearance escolhida; sua largura é proporcional à porcentagem concluída.
Neutral (valor padrão): usar em processos padrão, secundários ou fluxos que não impactam diretamente o negócio e não têm conotação de risco nem de sucesso. Ex.: o carregamento de uma tela secundária ou o avanço de um questionário de configuração.
Primary: reservar para processos críticos, fluxos principais do negócio ou tarefas em segundo plano de alto impacto que o usuário precisa acompanhar de perto. Ex.: a importação ou exportação em massa de um catálogo, ou o processamento de um pedido de pagamento.
Success: evitar durante o avanço contínuo de um processo; usar somente quando a tarefa terminar com sucesso em 100%, para dar um fechamento visual, ou em barras que medem uma meta. Ex.: um upload de arquivos concluído, ou o cumprimento de uma meta de vendas.
Warning: usar em barras de status ou consumo (métricas de capacidade) quando o volume atinge um limiar de risco, como 80%, que exige atenção preventiva. Ex.: o uso de armazenamento na nuvem ou o consumo de tokens de um plano perto de se esgotar.
Danger: usar em processos temporários quando a tarefa foi interrompida por uma falha, ou em barras de consumo quando se atingiu ou superou 100% da capacidade permitida. Ex.: uma falha crítica ao enviar um arquivo, ou o consumo de mensagens de um plano de IA que chegou ao limite.
AI generative (ai-generative): reservar para processos de inteligência artificial ou da Lumi que têm um avanço mensurável, para diferenciá-los visualmente dos processos comuns. Ex.: a geração de um lote de imagens de produto com IA, mostrando quantas já foram concluídas em relação ao total.
Default (0.5rem): usar na maioria dos contextos, quando a barra acompanha outro conteúdo sem competir por atenção.
Reduzida (0.25rem): usar em contextos muito densos, como um indicador estreito de cota dentro de um chat ou uma barra de status secundária.
O Progress Bar acompanha processos com avanço mensurável dentro de um card, um modal ou uma linha de uma lista: junto a um arquivo que está sendo enviado, dentro de um questionário de configuração, ou ao lado de um indicador de cota ou crédito consumido.
catalogo-produtos.csv
65% concluído
Importando produtos
40%
Acompanhar a barra com um texto que indique a porcentagem ou o status, quando o dado estiver disponível.
Evitar deixar a barra sozinha, sem nenhum texto que explique qual processo ela representa.
imagem-1.jpg
imagem-2.jpg
Usar várias barras de progresso em uma lista somente quando cada uma tiver seu próprio contexto claro (por exemplo, um arquivo por linha).
Evitar empilhar várias barras sem hierarquia nem contexto individual: o usuário não consegue distinguir a qual cada uma corresponde.
Excluindo produto em 2 s
Usar danger em uma contagem regressiva antes de uma ação destrutiva (por exemplo, excluir um produto), para reforçar visualmente que a ação está prestes a ser confirmada.
Excluindo produto em 2 s
Evitar uma appearance neutral ou primary para comunicar uma contagem regressiva destrutiva: sem a cor de alerta, o usuário não percebe que a ação é irreversível.
- Papel e valores expostos a leitores de tela: o componente renderiza role="progressbar" com aria-valuenow, aria-valuemin={0} e aria-valuemax={100}, para que o avanço seja anunciado de forma programática.
- Etiqueta acessível a cargo de quem o utiliza: como o componente não inclui um label próprio, é preciso associá-lo ao texto que descreve a tarefa (por exemplo, com aria-labelledby apontando para o Text que a nomeia) para que o contexto não dependa só do Box visual.
- Cor não como único sinal: além da appearance, acompanhar com a porcentagem em texto ou com um ícone, para que o status (por exemplo, um limite atingido em danger) seja compreendido mesmo sem distinguir a cor.
Instale o componente via terminal.
npm install @nimbus-ds/componentsimport React from "react";
import { ProgressBar } from "@nimbus-ds/components";
const Example: React.FC = () => <ProgressBar appearance="neutral" value={50} />;
export default Example;As propriedades adicionais são passadas para o elemento <ProgressBar>. Consulte a documentação do elemento div para ver a lista de atributos aceitos.
ProgressBar
| Name | Type | Default | Description |
|---|---|---|---|
value* | number | Progress value from 0 to 100 | |
appearance | 'ai-generative' | 'neutral' | Change the visual style of the progress bar. |
boxShadow | '0' | '0' | Applies a box shadow to the progress bar fill using the appearance color. |
height | string | '0.5rem' | Custom height for the progress bar. Any valid CSS height value. |
backgroundColor | 'neutral-background' | 'neutral-surfaceDisabled' | Change the background color of the progress bar track. |
ProgressBar.Skeleton
| Name | Type | Default | Description |
|---|---|---|---|
width | string | Width of the skeleton. Useful when the skeleton is inside an inline element with no width of its own. | |
className | string | ||
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. | |
data-testid | string | This is an attribute used to identify a DOM node for testing purposes. |
Ajude-nos a melhorar a documentação
Encontrou um problema ou tem uma sugestão? Conte para a gente.