Progress

Core Idea

Indicador visual (barra) do progresso de conclusão de uma tarefa, controlado externamente via prop value.

Key Concepts

• value: número (0-100) que define o preenchimento da barra.
• ProgressLabel / ProgressValue: subcomponentes opcionais para exibir rótulo textual e o valor numérico junto à barra.
• Composição: Progress > ProgressLabel, ProgressValue, ProgressTrack > ProgressIndicator.
• RTL: aceita prop dir; ProgressValue recebe função de formatação para números localizados (ex. algarismos arábicos).

Code Examples

"use client"

import * as React from "react"
import { Progress } from "@/components/ui/progress"

export function ProgressDemo() {
  const [progress, setProgress] = React.useState(13)

  React.useEffect(() => {
    const timer = setTimeout(() => setProgress(66), 500)
    return () => clearTimeout(timer)
  }, [])

  return <Progress value={progress} className="w-[60%]" />
}

• O que demonstra: barra de progresso controlada por estado React, atualizando de forma animada.

import { Progress, ProgressLabel, ProgressValue } from "@/components/ui/progress"

;<Progress value={56} className="w-full max-w-sm">
  <ProgressLabel>Upload progress</ProgressLabel>
  <ProgressValue />
</Progress>

• O que demonstra: composição com label e valor visível, sem precisar formatar manualmente.

<Progress value={value} className="w-full" />
<Slider value={value} onValueChange={(value) => setValue(value as number)} min={0} max={100} step={1} />

• O que demonstra: Progress pode ser dirigido por outro componente controlado (Slider), útil em UIs de configuração.

Anti-patterns

• Formatar número manualmente sem usar ProgressValue: perde a integração automática de acessibilidade/RTL que o subcomponente já oferece.

Key Takeaways

1. value é a única prop obrigatória; tudo mais é composição opcional.
2. Use ProgressLabel/ProgressValue em vez de texto solto ao lado da barra para manter a semântica de progresso.
3. Progress é 100% controlado: não há estado interno de progresso automático (ex. sem auto-incremento).

Connects To

• Slider: combinação comum para progress controlável interativamente.
• Spinner: alternativa para progresso indeterminado (sem valor numérico conhecido).