Progress

O componente Progress exibe um indicador de carregamento animado para informar ao usuário que uma operação está em andamento. Suporta dois modos: indeterminado (animação contínua) e determinado (exibe porcentagem).

Importação

import { Progress } from '@useblu/ocean-react';

Importação específica (recomendado para tree-shaking)

import { Progress } from '@useblu/ocean-react/Progress';

Importação de tipos TypeScript

import type { ProgressProps } from '@useblu/ocean-react';

// Uso em componente customizado
const MyComponent: React.FC<ProgressProps> = (props) => {
  return <Progress {...props} />;
};

Playground Interativo

Explore o componente Progress no playground interativo do Storybook:

🚀 Abrir no Storybook

Documentação Completa

Para documentação técnica detalhada, exemplos de uso e API completa, consulte o Storybook do Progress.

No Storybook você encontrará:

• ✅ Controles interativos para testar todas as props
• ✅ API gerada automaticamente com tipagem completa
• ✅ Exemplos visuais de todas as variantes e estados
• ✅ Playground para experimentação rápida

Uso básico

O Progress é usado para indicar que uma operação está em andamento:

<Progress />

Tamanhos

O Progress está disponível em três tamanhos diferentes:

Small

<Progress size="sm" />

Medium (padrão)

<Progress size="md" />

Large

<Progress size="lg" />

Veja todos os tamanhos juntos:

🚀 Abrir no Storybook

Variante On Color

Use a prop onColor quando o Progress for exibido sobre um fundo colorido ou escuro:

<div>
  <Progress onColor />
</div>

Comparação entre as variantes:

🚀 Abrir no Storybook

Progress Determinado

Use a prop percentage para exibir um progresso determinado com porcentagem específica (0-100):

<Progress percentage={50} />

Diferentes porcentagens

<div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>
  <Progress percentage={0} />
  <Progress percentage={25} />
  <Progress percentage={50} />
  <Progress percentage={75} />
  <Progress percentage={100} />
</div>

Tamanhos com porcentagem

<div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>
  <Progress size="sm" percentage={75} />
  <Progress size="md" percentage={75} />
  <Progress size="lg" percentage={75} />
</div>

Veja todas as variantes de porcentagem:

🚀 Abrir no Storybook

API

Props

Prop	Tipo	Padrão	Descrição
size	'sm' | 'md' | 'lg'	'md'	Define o tamanho do componente de progresso
onColor	boolean	false	Define se o progresso deve ser exibido sobre fundo colorido
percentage	number | undefined	undefined	A porcentagem do progresso (0-100). Quando undefined, o progresso é indeterminado (modo animado)
className	string	-	Classes CSS adicionais

Classes CSS

O componente Progress utiliza as seguintes classes CSS para customização:

Classes principais

Classe	Descrição
.ods-progress	Classe base do componente
.ods-progress--sm	Tamanho small do progresso (16px)
.ods-progress--md	Tamanho medium do progresso (24px, padrão)
.ods-progress--lg	Tamanho large do progresso (32px)
.ods-progress--on-color	Variante para fundos coloridos/escuros
.ods-progress--indeterminate	Modo indeterminado (animação contínua)
.ods-progress--determinate	Modo determinado (com porcentagem)

Elementos SVG

O componente Progress utiliza SVG para a animação. As classes afetam os seguintes elementos:

Modo Indeterminado

Elemento	Descrição
svg	Container do SVG animado
svg circle	Círculo de fundo do progresso
svg path	Caminho da animação do progresso

Modo Determinado

Classe	Descrição
.ods-progress__determinate	Container SVG do modo determinado
.ods-progress__track	Círculo de fundo (track)
.ods-progress__fill	Círculo de preenchimento (progresso)

Acessibilidade

• ✅ Animação suave e não intrusiva
• ✅ Usa role="progressbar" para screen readers
• ✅ Atributos ARIA (aria-valuenow, aria-valuemin, aria-valuemax) no modo determinado
• ✅ Contraste adequado em todos os estados
• ✅ Não interfere na navegação por teclado

Melhores práticas

✅ Faça

• Use Progress indeterminado para operações de duração desconhecida
• Use Progress determinado quando souber a porcentagem de conclusão
• Combine com texto explicativo quando necessário
• Use o tamanho apropriado para o contexto (sm para inline, lg para tela cheia)
• Use onColor em fundos escuros ou coloridos

❌ Não faça

• Não use Progress para operações instantâneas
• Não use múltiplos Progress simultaneamente na mesma área
• Não omita o onColor em fundos escuros
• Não use Progress como placeholder de conteúdo
• Não use valores de percentage fora do intervalo 0-100

Visão geral completa

Veja todas as variantes do Progress em ação:

🚀 Abrir no Storybook

Links relacionados

• Button - Para ações que podem mostrar Progress
• Modal - Para usar Progress em modais de carregamento
• Storybook - Progress - Documentação técnica