Progress ring
A progress ring shows how far a task has gone on a known scale, as an arc. It only reports progress; it can't be focused or clicked.
<tk-progress-ring value="72" show-value label="Uploading photos"></tk-progress-ring>
Anatomy
| Part | What it is |
|---|---|
tk-progress-ring |
the element; role="progressbar", never focusable |
| track | the full circle: the whole scale |
| arc | the done part, from 12 o'clock clockwise, with round ends |
| center value | the value in the middle, with show-value |
| default slot | your own label or status text, beside the ring |
Variants
<tk-progress-ring value="40" show-value label="Sync"></tk-progress-ring> <tk-progress-ring value="100" intent="success" label="Sync">Synced</tk-progress-ring> <tk-progress-ring value="40" intent="error" label="Sync">Sync failed</tk-progress-ring>
accent(default): ordinary progress, including at 100%.success: a finished task, with text that says so.error: a failed task, with text that says what went wrong.
Always pair intent with text; color alone doesn't tell everyone.
Sizes
<tk-progress-ring value="72" size="small" show-value label="Export"></tk-progress-ring> <tk-progress-ring value="72" show-value label="Export"></tk-progress-ring> <tk-progress-ring value="72" size="large" show-value label="Export"></tk-progress-ring> <tk-progress-ring value="72" size="xlarge" show-value label="Export"></tk-progress-ring>
size |
Diameter | Stroke | Value |
|---|---|---|---|
small |
24px | 2px | beside the ring |
medium (default) |
40px | 4px | in the center |
large |
64px | 4px | in the center |
xlarge |
96px | 8px | in the center |
On medium the center value is 10px. If people must read it easily, use large or
show the value in text.
Value
- Set
value; it's clamped betweenmin(0) andmax(100). Without a value the ring draws empty and warns in the console. show-valueshows72%, or18 of 25withvalue-format="fraction".- Text in the default slot appears beside the ring.
When to use
- Use a progress ring when you know the fraction and space is small or square, or the value should sit in the middle.
- Use a
Progress bar in a wide, linear place, such as an upload row. - Use a
Spinner when you can't measure the progress. The ring always has a value; it never spins.
Content
- Name the task in
label: "Uploading photos", not "Progress". - In a status, say what happened: "Synced", "Sync failed".
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
| Use a ring when you know the fraction | Spin a ring forever; use a spinner |
| Use it for work that advances | Use it for a fixed amount, such as storage used |
Pair intent with text |
Rely on color alone for success or failure |
| Keep the arc color at 100% | Switch to green automatically on completion |
Related
Progress bar : the same value as a bar, with an indeterminate mode.Spinner : a wait with no scale.
API
Attributes
| Attribute | Type | Default | What it does |
|---|---|---|---|
value |
number | unset | position on the scale; required |
min |
number | 0 |
start of the scale |
max |
number | 100 |
end of the scale |
intent |
accent | success | error |
accent |
arc color; pair it with text |
show-value |
boolean | false |
shows the value, in the center or beside on small |
value-format |
percent | fraction |
percent |
72% or 18 of 25 |
size |
small | medium | large | xlarge |
medium |
24, 40, 64, or 96px |
label |
string | unset | accessible name |
Slots
| Slot | Content |
|---|---|
| default | a label or status beside the ring; announced politely |
Events
None.
Tokens
| Part | Token |
|---|---|
| track | surface/sunken |
| arc | fill/accent, fill/success, fill/error |
| center value | text/default, font-weight-semibold |
| value beside, slot text | text/secondary, Label Small |
Values per theme:
Accessibility
Built in:
role="progressbar"witharia-valuemin,aria-valuemax,aria-valuenow, andaria-valuetext(the readout text).- Slot text sits in a polite live region, so a status or error is announced without moving focus.
- Never focusable and never a Tab stop.
- With reduced motion, the arc jumps to its new value.
Your part:
- Name every ring with
label,aria-label, oraria-labelledby. An unnamed ring warns in the console. - Pair
successanderrorwith text.
Contrast limits
- Accent arc against the track: at least 3:1 with the blue, indigo, purple, and black
primary colors. In light it falls to 1.65–2.63:1 with orange, green, mint, teal, brown,
and gray; in high contrast to 2.02–2.94:1 with orange, green, mint, teal, and gray. Dark
holds 3:1 with every color. Where it falls short, turn on
show-value. - Success and error arcs: at least 3.50:1 in every theme.