Spin when the wait has no known end. A bar that creeps and then jumps promised a number it never had.
Skeleton when the shape of what is coming is the better placeholder.
Steps when the stages have names and the reader needs to know which one they are in.
Result once the work is over and the outcome needs explaining.

Line, circle and dashboard

Pick type first, since it decides which other props apply.

line is the default and fills its parent's width. Use it in a row with other content: a table cell, a list item, the strip under an upload. Only a line takes the pair and object forms of size, and only a line can move its value with percentPosition.
circle when the value is the content of its surface: a stat tile, a quota card, a gauge. It takes one number for its size and shows the value in the middle.
dashboard is a circle with a gap, read as a dial. The gap defaults to the bottom at 75 degrees. Move it with gapPlacement and resize it with gapDegree.
Use one type per surface. A bar, a ring and a dial in one card read as three different measurements.

percent, and the second run

percent runs from 0 to 100 and defaults to 0. Values out of range are clamped without a warning, so compute it from the same source as the text beside the bar.

At 100, the status turns to success. With no status, a bar at 100 shows the success color and a check, so a value that rounds up to 100 announces a finish too early. Round down with Math.floor.
success takes { percent, strokeColor } and draws a second, darker run inside the first, for two readings of one total: done against started, uploaded against queued.
If the inner run is not part of the outer one, it needs its own bar.
Label both runs, with a legend or a tooltip. The bar alone cannot say which is which.
With success.percent, the value the bar announces is the success percent. The Accessibility tab has the detail.

status, and what color is allowed to mean

status takes four values.

normal is the default resting bar.
active adds a shimmer to a bar, for work running right now. Remove it as soon as the work stalls.
success for a finished run. It applies on its own at 100, so set it yourself only when the bar is done below 100.
exception for a failed run. It shows the error color and a cross.
There is no warning status. For a warning, set strokeColor="var(--ant-color-warning)".

Do not let color say the outcome alone. A green bar and a red bar of the same length look the same to a reader who cannot tell the hues apart, so put a sentence beside the bar. Do not use strokeColor to restate a status either: it would disagree with the icon the status still shows.

format, and the label in the middle

format receives (percent, successPercent) and returns what the value slot shows. Left alone, it shows the percentage.

Use it when the reader thinks in another unit. “3 of 8 files” and “1.2 of 5 GB” answer the question directly, where “37%” makes the reader work it out.
format replaces the status icon too. The value text and the icon share one slot, so a custom format shows your text even at success or exception. Return an icon from it if you still want one.
Keep the label short. On a circle it sits inside the ring, and on a bar a long label narrows the bar.
An inner value needs a taller bar. percentPosition takes a type of inner or outer and an align of start, center or end. With inner, give the bar a size tall enough for the text. It does not apply to a stepped bar.
showInfo={false} removes the label. Then put the number in text nearby, or nothing on screen says it.

strokeColor and gradients

strokeColor paints the filled run and railColor the track behind it. Both take a CSS color.

Use theme colors. A var(--ant-color-*) color follows the theme into dark mode. A hex does not.
A gradient takes { from, to } or percentage stops ({ "0%": …, "100%": … }), with an optional direction.
A gradient is decoration. The reader reads the bar's length, so use one for a hero element, not for a bar that reports.
A circle or dashboard with a gradient ignores strokeLinecap. On a bar, "butt" and "square" give the same flat end, so the difference only shows on circles.
An array of colors only works with steps. On a plain bar only the first color is used.

steps

steps splits the bar into a fixed number of segments, filled from the start.

Use it when the total is small and countable: five uploads, eight checks, three of twelve lessons.
percent still drives it, and the filled count is rounded. Pass rounding={Math.floor} when a half-done step must not look done.
A bar takes a number. A circle or dashboard takes { count, gap }.
steps changes what strokeColor means. An array colors each segment instead of making a gradient, and percentPosition stops applying.
It is not the Steps component. A segment has no name, no state and nothing to click.

size, and work with no number

Size pairs only work on a bar. size takes one of four shapes.

A preset, small or medium. default is deprecated: write medium.
A number, which on a circle or dashboard is the diameter.
A [width, height] pair or a { width, height } object, for bars only. On a circle or dashboard they warn at runtime.
size replaces the deprecated width on circles and strokeWidth on bars.
Small circles show their value in a tooltip. At size={20} or less, a circle hides its text and shows format's result on hover, so write a full sentence there and keep the number in text nearby.

Progress has no indeterminate mode, and 0 means none, not unknown. When you cannot compute a share, show a Spin and switch to a bar once the total is known.

Popover QRCode

On This Page

Usage