Raft 设计系统
English

组件 · 反馈

Progress

A bar that shows how far a measurable task has gone, such as an upload or usage against a limit, with a label and its value.

稳定也叫 ProgressBar, Loading
import { Progress } from "@botiverse/raft-ui";
本页尚未翻译
译文完成之前，这里显示英文原文。 阅读英文版

A progress bar shows how far something with a known percentage has gone: an upload, a file being processed, usage against a quota. Next to it, a label says what it is and how far it has got. Which loading indicator fits which wait is in Choosing a component.

progress/compositions/preview

When to use

SituationUse
The percentage is knownProgress
The duration is unknownSpinner, not a progress bar
The layout of what is loading is knownSkeleton

Anatomy

  • Progress: the root; takes the value. Required.
  • ProgressHeader: an optional row above the track, holding ProgressLabel (what it is) and ProgressValue (how far, in Space Mono).
  • ProgressTrack: the fill-muted track. Required.
  • ProgressIndicator: the fill, a sticker with an ink edge. Required.

Variants

VariantUse for
The default (variant="primary")Progress of any kind: an info fill
variant="warning"Usage at 90% of a limit or more
CompleteWhen value reaches the maximum the fill turns success on its own
  • Don't use variant="danger": reaching a limit interrupts, it isn't irreversible (Color).
  • information and accent are the same as the default. Use the default.
progress/compositions/embedded-progress

States

  • Don't show a bar whose percentage can't be computed. Use a Spinner instead of a fake or indeterminate bar.

Content

  • Name what is in progress in ProgressLabel: "Uploading design-crop.png", "Agent hours this month".
  • Show how far it has got in ProgressValue, as a percentage or as an amount out of the limit.

Accessibility

Progress wraps Base UI's Progress, which gives it role="progressbar" and its value.

  • ProgressLabel gives the bar its accessible name. Without a visible label, pass aria-label to Progress.
  • Keep ProgressLabel even when you leave out ProgressValue.

Rules

  • Put a bar inside a file card, thumbnail or other rounded container on its own thin track, never along its edge (Shape).

API

Progress

Prop类型默认值
size"sm" | "md" | "lg""md"
variant"primary" | "accent" | "warning" | "danger" | "information" | "success""primary"
aria-valuetextA string value that provides a user-friendly name for `aria-valuenow`, the current value of the progress bar.string
formatOptions to format the value.Intl.NumberFormatOptions
getAriaValueTextAccepts a function which returns a string value that provides a human-readable text alternative for the current value of the progress bar.(formattedValue: string, value: number | null) => string
localeThe locale used by `Intl.NumberFormat` when formatting the value. Defaults to the user's runtime locale.string | Intl.Locale | readonly (string | Intl.Locale)[]
maxThe maximum value.number100
minThe minimum value.number0
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component.ReactElement | ((props, state) => ReactElement)
value (required)The current value. The component is indeterminate when value is `null`.number

Also takes the attributes of its element.

ProgressHeader

接受其元素的全部属性。

ProgressIndicator, ProgressLabel, ProgressTrack

Prop类型默认值
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component.ReactElement | ((props, state) => ReactElement)

Also takes the attributes of its element.

ProgressValue

Prop类型默认值
children(formattedValue: string | null, value: number | null) => React.ReactNode
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component.ReactElement | ((props, state) => ReactElement)

Also takes the attributes of its element.

相关组件