# ARIA progressbar elements must have an accessible name.

> Canonical HTML version: https://rocketvalidator.com/accessibility-validation/accesslint/0.16/labels-and-names/aria-progressbar-name
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

Elements with `role="progressbar"` must have an accessible name so that screen reader users can identify what process or task the progress indicator is tracking. Without a name, a screen reader may announce something like "progressbar 60%" with no context, leaving the user unable to determine whether the indicator refers to a file upload, a form submission, a page load, or something else entirely.

This rule applies whenever a native or custom element is assigned `role="progressbar"`. Screen reader users depend on the accessible name to distinguish between multiple progress indicators on the same page and to understand what each one measures. Sighted users can usually infer meaning from surrounding text or visual layout, but that context is lost when the progress bar lacks a programmatic name.

## How this relates to WCAG

This rule maps to [WCAG 4.1.2 Name, Role, Value (Level A)](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html). That success criterion requires all user interface components to have a name that can be programmatically determined. A progress bar without an accessible name fails this requirement because assistive technology cannot convey the component's purpose to the user.

## How to fix it

There are two common ways to give a progress bar an accessible name:

1. Add an `aria-label` attribute directly to the element. Use a short, descriptive phrase that identifies the process being tracked.
2. Use `aria-labelledby` to point to the `id` of a visible text element that already describes the progress bar, such as a heading or label.

Choose `aria-labelledby` when visible text near the progress bar already describes it. This keeps the visible label and the accessible name in sync. Use `aria-label` when no visible label exists or when adding one would not fit the design.

If the progress bar also needs to communicate its current value in a human readable way (for example, "3 of 10 files"), use `aria-valuetext` alongside the numeric `aria-valuenow`.

## Examples

### Missing accessible name

This progress bar has no `aria-label` or `aria-labelledby`, so a screen reader cannot tell the user what process it tracks.

```html
<div role="progressbar" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
  50%
</div>
```

### Fixed with `aria-label`

Adding `aria-label` gives the progress bar a clear, programmatic name.

```html
<div
  role="progressbar"
  aria-label="File upload progress"
  aria-valuenow="50"
  aria-valuemin="0"
  aria-valuemax="100">
  50%
</div>
```

### Fixed with `aria-labelledby`

When a visible heading or label already describes the progress bar, reference it with `aria-labelledby`.

```html
<h3 id="upload-heading">Uploading photos</h3>
<div
  role="progressbar"
  aria-labelledby="upload-heading"
  aria-valuenow="50"
  aria-valuemin="0"
  aria-valuemax="100">
  50%
</div>
```

### Multiple progress bars on one page

When several progress bars appear together, each one needs its own distinct name so users can tell them apart.

```html
<div
  role="progressbar"
  aria-label="Video conversion"
  aria-valuenow="30"
  aria-valuemin="0"
  aria-valuemax="100">
  30%
</div>

<div
  role="progressbar"
  aria-label="Audio extraction"
  aria-valuenow="75"
  aria-valuemin="0"
  aria-valuemax="100">
  75%
</div>
```