# Progress Bar

> How to build an accessible progress bar with the native progress element or ARIA, and the tests Evinced runs on its role, name, value, and range.

Source: https://knowledge.evinced.com/web/ui-patterns/progress-bar

A progress bar tells users that a task is underway and how far it has gone. An accessible progress bar carries the `progressbar` role, an accessible name that identifies the task, and a value within its range when progress can be measured.

A progress bar shows how much of a task has been completed, such as a file upload, a download, or the steps of a long-running process. It confirms that their request has been received.

A progress bar reports a current value within a range, and the value moves toward the maximum as the task advances. When the amount of work done can't be measured, the progress bar is indeterminate: it reports that the task is running without saying how far along it is.

A progress bar is read-only. Users watch it change but can't set its value, so it isn't in the tab order and has no keyboard or pointer behavior of its own.

There are two ways to build one. The native HTML `<progress>` element carries the role, the value, and the range on its own. A custom progress bar is a generic element given `role="progressbar"` and ARIA value properties, which code keeps up to date as the task advances.

A progress bar differs from a meter, which reports a measurement within a known range, such as disk usage or battery charge, rather than progress through a task. It also differs from a slider, which shows a value in a range that users set themselves.

## When to Use

Use a progress bar when:

-   A task takes long enough that users benefit from knowing it's still running, such as an upload, a download, an export, or an installation.
-   You can measure how much of the task is done, or you can't yet but want users to know the work is underway (an indeterminate progress bar).
-   The value only moves in one direction, toward completion.

Do not use a progress bar when:

-   The value is a measurement that rises and falls, such as disk usage, battery charge, or a score. Use a meter.
-   Users choose the value. Use a slider.
-   No task is underway, so the value won't change on its own.

## Examples

Code in this section is meant to demonstrate techniques rather than requirements and lacks features needed in a production application.

### Native HTML progress bar

The `<progress>` element needs only HTML. Its `value` and `max` attributes report how far the file upload has gone, and the `<label>` element names it. The text inside `<progress>` is fallback content for browsers that can't render the element, not its accessible name.

**Native progress bar HTML**

```html
<label for="file-upload">
  Uploading file
</label>
<progress
  id="file-upload"
  value="70"
  max="100">70%</progress>
```

### Custom ARIA progress bar

The custom progress bar carries `role="progressbar"` and takes its accessible name from the visible label through `aria-labelledby`. It leaves `aria-valuemin` and `aria-valuemax` off, since its range is the default 0 to 100. Its `aria-valuetext` reads "42 percent compressed" rather than a bare percentage.

The inner fill element is decoration, and it's presentational, like every descendant of an element with `role="progressbar"`. The visible text below the bar repeats the value text, so `aria-hidden` keeps screen reader users from hearing it twice.

**ARIA progress bar HTML**

```html
<div id="compress-label">
  Compression progress
</div>
<div
  id="compress-progress"
  class="progressbar"
  role="progressbar"
  aria-labelledby="compress-label"
  aria-valuenow="42"
  aria-valuetext="42 percent compressed">
  <div
    class="progressbar__fill"
    style="width: 42%"></div>
</div>
<div
  id="compress-status"
  aria-hidden="true">
  42% compressed
</div>
```

**ARIA progress bar CSS**

The fill draws a border rather than a background, so it stays visible in forced colors modes, such as Windows High Contrast.

```css
.progressbar {
  position: relative;
  width: 100%;
  border: 2px solid gray;
}


.progressbar__fill {
  height: 0;
  border-bottom: 8px solid gray;
}
```

JavaScript updates the value, the value text, the fill, and the visible text together, so what users see and what assistive technology reports stay in step.

**ARIA progress bar JavaScript**

```javascript
function setCompressed(percent) {
  const value = Math.min(
    100,
    Math.max(0, Math.round(percent))
  )
  const bar = document.getElementById('compress-progress')
  bar.setAttribute('aria-valuenow', String(value))
  bar.setAttribute(
    'aria-valuetext',
    `${value} percent compressed`
  )
  bar.querySelector('.progressbar__fill').style.width = `${value}%`
  document.getElementById('compress-status').textContent =
    `${value}% compressed`
}
```

## Structure and Semantics

Users need to know what task a progress bar tracks and how far along it is. A progress bar conveys that through three things: the `progressbar` role, an accessible name that identifies the task, and a value within a range.

The native `<progress>` element supplies the role and reports its value from its `value` and `max` attributes. Its minimum is always 0, so it has no `min` attribute. Its `max` defaults to 1, not 100. Leaving `value` off makes it indeterminate. The `<progress>` element can be named with a `<label>` element, like a form field.

A custom progress bar declares `role="progressbar"` on the element that represents the whole bar, and reports its value with `aria-valuenow`. Its range defaults to 0 to 100, so `aria-valuemin` is needed only when the minimum isn't 0, and `aria-valuemax` only when the maximum isn't 100. Leaving `aria-valuenow` off makes it indeterminate.

The `progressbar` role takes its accessible name only from the author, never from its contents, and makes all of its descendants presentational. Text placed inside a custom progress bar doesn't name it, and a heading or a link placed inside it loses its role. Keep the label and any related controls outside the progress bar.

| Attribute | How to use |
| :-- | :-- |
| `role="progressbar"` | Custom progress bar. Set on the element representing the whole bar, not on its fill. Not needed on `<progress>`, which carries the role implicitly. |
| `aria-valuenow` | Custom progress bar. Set to the current value and update it as the task advances. Omit it when the value is indeterminate. A native `<progress>` uses its `value` attribute instead. |
| `aria-valuemin` / `aria-valuemax` | Custom progress bar. Set `aria-valuemin` only when the minimum isn't 0, and `aria-valuemax` only when the maximum isn't 100. A native `<progress>` uses its `max` attribute instead. |
| `aria-valuetext` | Either construction. Optional. Set to a readable form of the value when a percentage alone isn't meaningful, such as "Step 2 of 4". |
| `aria-labelledby` / `aria-label` | Either construction. Names the task. Point `aria-labelledby` at visible text, and use `aria-label` only when there's none. A native `<progress>` can use a `<label>` element instead. |

### Role

A progress bar exposes the `progressbar` role on the element that carries its value and its accessible name. The `<progress>` element supplies the role on its own. A custom progress bar declares `role="progressbar"` on its outer element, the one holding `aria-valuenow`, not on the fill or the track inside it.

**Has the correct role**

**Reported as:** Element has incorrect role

A progress bar must expose the `progressbar` role.

When a custom progress bar is built from styled `<div>` elements with no role, assistive technology exposes it as plain content or ignores it, and screen reader users aren't told that a task is underway or how far it has gone. The value properties also have no role to attach to, so their value isn't reported either.

Use the `<progress>` element, or set `role="progressbar"` on the element representing the whole bar.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Applies role to the correct element**

**Reported as:** Incorrect root element

**Sanity check.** Evinced checks that the `progressbar` role sits on the element that holds the progress bar's value and accessible name, not on an element around it or inside it. This check runs on every UI pattern, not only on progress bars.

A progress bar should carry the `progressbar` role on its outer element, together with its value properties and its accessible name.

When the role sits on the inner fill while the value properties and the name sit on the wrapper, or the other way around, no single element holds the role, the value, and the name. Screen reader users may get a progress bar with no value or no name, next to an element with a value and no role.

Put `role="progressbar"`, the value properties, and the accessible name on one element, and keep the fill and track free of roles.

### Accessibility label

A progress bar needs an accessible name that identifies the task it tracks, such as "Uploading file" or "Export progress". Without one, screen reader users hear only a role and a percentage. The name never comes from the progress bar's contents, so it has to be supplied. Use a `<label>` element for a native `<progress>`, or `aria-labelledby` pointing at visible text for either construction. Fall back to `aria-label` when there's no visible text.

**Names a container that needs one**

**Reported as:** Missing contextual labeling

A progress bar must have an accessible name that says which task it tracks.

When a progress bar has no name, screen reader users hear something like "progress bar, 42 percent" with no way to know what the task is. On a page with several progress bars, they can't tell the tasks apart, or which one has finished. A visible label beside the bar doesn't help unless it's connected.

Connect the visible label to the progress bar, with a `<label>` element for a native `<progress>` or `aria-labelledby` for either construction. When there's no visible label, set `aria-label`.

**Severity:** Moderate

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships) (A) | Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. |
| EN 301 549 | [9.1.3.1 Info and Relationships](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |

### aria-valuetext

When a percentage alone doesn't tell users where the task stands, `aria-valuetext` gives a readable form of the value, such as "Downloading file 3 of 10, 50 percent complete". Assistive technology reports the text in place of the number, so update the text every time the value changes, and keep `aria-valuenow` set alongside it on a custom progress bar. A native `<progress>` element can carry `aria-valuetext` too.

**Uses value text to add meaning**

**Reported as:** Meaningful aria-valuetext

A progress bar's `aria-valuetext` should say something its number doesn't.

When `aria-valuetext` repeats the value, such as "50" for a value of 50, screen reader users hear less than the default percentage would have told them. The text also replaces the number in what assistive technology reports, so if it isn't updated with the value, screen reader users hear progress the task has already passed.

Leave `aria-valuetext` off when the percentage speaks for itself. When it doesn't, set text that adds the missing context, such as the step or the file count, and update it in the same place as the value.

**Severity:** Minor

This issue is classified as "**Best Practice**," meaning it isn't tied to a specific WCAG success criterion or any other regulation or standard; however it still affects the experience of some users. These issues fall outside formal compliance requirements, yet addressing them improves usability and accessibility in practice.

### Values

A progress bar reports how far its task has gone as a value within a range, and assistive technology usually presents that value as a percentage of the range. When the value can't be measured yet, the progress bar is indeterminate: leave out `value` on a `<progress>` element or `aria-valuenow` on a custom progress bar, and let the accessible name say what's happening.

The following example shows an indeterminate progress bar in each construction.

```html
<label for="sync-progress">
  Syncing contacts
</label>
<progress id="sync-progress"></progress>


<div
  role="progressbar"
  aria-label="Syncing contacts"></div>
```

**Leaves native values to HTML**

**Reported as:** Avoid ARIA values on native inputs

A native `<progress>` element must not also carry `aria-valuenow`, `aria-valuemin`, or `aria-valuemax`.

When a `<progress>` element has ARIA value properties alongside its `value` and `max` attributes, the two can disagree. Script updates `value` as the task advances while the ARIA properties keep their first values, so screen reader users can hear a figure the progress bar has long since passed.

Remove the ARIA value properties and let `value` and `max` report the progress. `aria-valuetext` has no native counterpart, so keep it when the number needs explaining.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Orders its limits low to high**

**Reported as:** Min value is greater than the max value

A progress bar's minimum must be lower than its maximum.

When `aria-valuemin` is greater than `aria-valuemax`, the range contains no value. Assistive technology can't place the value within it, so screen reader users hear a negative percentage or a bare number with no sense of how far the task has gone.

Sort the two limits before declaring them, including limits taken from data, so the smaller one is always the minimum.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Reports its value and its limits**

**Reported as:** Missing range attributes

A progress bar with a measurable value must report it, together with its range, to assistive technology.

When a custom progress bar moves its fill but never sets `aria-valuenow`, screen reader users are told the task is underway but not how far it has gone. Missing limits give the wrong figure instead. A custom progress bar with no `aria-valuemax` is treated as running to 100, so screen reader users hear 3 of 8 files as "3 percent".

Set `aria-valuenow` and update it in the same code that moves the fill. Set `aria-valuemin` when the minimum isn't 0 and `aria-valuemax` when the maximum isn't 100, or `max` on a `<progress>` element. Leave the value off only when the progress can't be measured.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Spans more than a single value**

**Reported as:** Range has equal min and max values

A progress bar's range must have room for more than one value, with a maximum above its minimum.

When the minimum and maximum are equal, such as a maximum taken from a file count that's still 0 before the list loads, every value is both the start and the end. Assistive technology can't express progress as a share of a range with no width, and screen reader users hear a figure that never changes as the task advances.

Check that the limits differ before declaring them. When the size of the task isn't known yet, leave the value off so the progress bar is indeterminate until it is.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

### aria-invalid

A progress bar has no invalid state to report. Users never enter its value, and ARIA 1.2 deprecated `aria-invalid` on the `progressbar` role. A value that falls outside the range is a fault in the code that sets it, so fix the value rather than flagging it.

**Does not declare aria-invalid**

**Reported as:** False aria-invalid value

A progress bar must not carry `aria-invalid`.

A progress bar isn't an input, so users can't correct its value. When a progress bar carries `aria-invalid="true"`, screen reader users are told about an error they can do nothing about. On a normal reading, they may decide the task has failed and cancel or restart it. A value outside the range isn't a state to report either: it's a fault in the code that sets it, which the code has to fix.

Remove `aria-invalid` from the progress bar, and keep its value within its range. When the task fails or stalls, such as an upload stuck at 100 percent, say so in text near the progress bar, set `aria-describedby` on the progress bar to that text's `id`, and drive error styling from a class.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Keeps the value within its bounds**

**Reported as:** Value out of range

A progress bar's reported value must sit at or between its minimum and maximum.

When the value comes from data with a different range, or the maximum changes without the value following, the progress bar reports a figure its range can't contain. Screen reader users may hear "120 percent" on a range that stops at 100, or a percentage that bears no relation to the work done.

Clamp the value to the limits whenever the value or the limits change, and set all three from the same source.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

### Disabled

A progress bar is read-only, so it has nothing to disable. The `<progress>` element has no `disabled` attribute, and ARIA 1.2 deprecated `aria-disabled` on the `progressbar` role. When a task pauses or stops, say so in the value text or in text near the progress bar rather than through a disabled state.

**Never declares a disabled state**

**Reported as:** Component does not support disabled state

A progress bar must not carry a disabled state.

When `disabled` or `aria-disabled` is set on a progress bar, assistive technology may drop the state silently or report the progress bar as unavailable, which tells users nothing about the task. A paused upload reported as unavailable doesn't say whether it will resume.

Remove `disabled` and `aria-disabled` from the progress bar. Report a paused or stopped task in its `aria-valuetext`, such as "Paused at 40 percent", or in visible text beside it, and style the inactive look with CSS.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Disables only elements that support it**

**Reported as:** Element type does not support disabled state

An element in a progress bar must carry `disabled` or `aria-disabled` only when its role supports a disabled state.

When the state sits on an element whose role has none, such as a wrapper, a list item or a heading, assistive technology may drop it or report it on something users can't operate, while the control that really is unavailable is still reported as available.

Remove the attribute, as the section intro describes. When a related control is unavailable, disable that control instead.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Avoids conflicting disabled states**

**Reported as:** Conflicting disabled values

A progress bar must not carry disabled values that conflict.

When a progress bar carries both `disabled` and `aria-disabled` with values that disagree, such as `disabled` with `aria-disabled="false"`, assistive technology can report a state different from the one the browser applies, on an element that has no disabled state to report.

Remove both attributes from the progress bar, as the section intro describes, and report a paused or stopped task in its `aria-valuetext` or in text beside it.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Keeps disabled off the progress bar**

**Reported as:** Element does not support the disabled attribute

A progress bar must not carry the HTML `disabled` attribute.

When `disabled` is set on a `<progress>` element or on an element with the `progressbar` role, browsers ignore it. Nothing changes for users, and screen reader users hear nothing about a task the design may show as paused or stopped.

Remove the attribute, as the section intro describes. Report a paused or stopped task in the progress bar's `aria-valuetext` or in text beside it, and style the inactive look with CSS.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

### Forbidden interactive children

A progress bar contains no interactive elements. The `progressbar` role makes everything inside it presentational, so a control placed inside loses its role and accessible name. A control related to the task, such as a button that cancels an upload, belongs beside the progress bar.

**Avoids nested interactives**

**Reported as:** Forbidden interactive children; Nested interactive elements

A progress bar must not contain an interactive element.

When a link or a button sits inside a progress bar, or is owned by one through `aria-owns`, it becomes presentational and drops out of the accessibility tree even though it's visible on screen. Screen reader users can't find or operate it, and keyboard users may tab to a control that assistive technology doesn't describe.

Move the control out of the progress bar, and out of any `aria-owns` list on it, and place it beside the progress bar with its own role, accessible name, and tab stop.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

## Relationships

A progress bar relates to its label and, when it tracks something loading on the page, to the region that's loading. A `<label>` element names a native `<progress>`, and `aria-labelledby` names either construction from visible text elsewhere.

When a progress bar tracks the loading of a particular region of the page, set `aria-describedby` on that region to the progress bar's `id`, and set `aria-busy="true"` on the region until it finishes loading. Assistive technology can then report that the region isn't ready and identify the progress bar that tracks it.

### aria-owns

A progress bar is a single element whose children are presentational, so a label, a status message, or a cancel button sits outside it and relates to it by reference. Nothing about a progress bar calls for `aria-owns`.

**Avoids aria-owns**

**Reported as:** Avoid aria-owns

**General check.** Evinced checks that the progress bar doesn't use `aria-owns` to claim elements elsewhere in the document as its children. This check runs on every UI pattern, not only on progress bars.

A progress bar should not own other elements with `aria-owns`.

When a progress bar owns its label, a status message, or a button, those elements become its children, so they're presentational too. Depending on the browser and assistive technology, screen reader users may find the owned content missing from browse mode, folded into the progress bar's name, or read twice. When the owned content is focusable, focus can land on something with no role or name.

Remove `aria-owns` from the progress bar and keep the content outside it. Reference the label with `aria-labelledby` and any supporting text with `aria-describedby`.

## Operation

A progress bar has no keyboard or pointer operation of its own: users read its progress, and it takes no focus. When script on the page handles keys around it, the test below applies.

### Event listener type

When script in a progress bar responds to keys, it listens for `keydown` or `keyup`. The `keypress` event is deprecated, and browsers don't fire it for many keys, including the arrow keys, Home, End and Escape.

**Avoids the keypress event**

**Reported as:** Deprecated keypress listener

A progress bar's key handling should use `keydown` or `keyup`, not `keypress`.

When a handler listens for `keypress`, keys the browser doesn't send through that event go unanswered, and keyboard users find the progress bar ignoring keys it's meant to respond to.

Replace each `keypress` listener with a `keydown` listener, and read the key from `event.key`.

**Severity:** Minor

This issue is classified as "**Best Practice**," meaning it isn't tied to a specific WCAG success criterion or any other regulation or standard; however it still affects the experience of some users. These issues fall outside formal compliance requirements, yet addressing them improves usability and accessibility in practice.

## FAQ

**Which WCAG success criteria do the progress bar issues relate to?**

Most relate to 4.1.2 Name, Role, Value: the `progressbar` role, reporting the value and its limits, ordering the limits and giving the range room for more than one value, leaving native values to HTML, keeping the value within its bounds, the invalid and disabled states, and keeping interactive elements out of the progress bar. The accessible name relates to 1.3.1 Info and Relationships.

Meaningful value text maps to no WCAG success criterion and is a best practice.

**Why are some progress bar issues marked as Critical and others as Minor?**

Severity reflects how much an issue gets in users' way. Critical issues stop users outright:

-   A progress bar with no role
-   A measurable value or its limits not reported
-   Limits in the wrong order or equal
-   ARIA values that contradict a native progress bar

Serious issues confuse users though they can still follow the task:

-   An invalid or disabled state
-   A value outside the range
-   An interactive element inside the progress bar

Moderate issues leave users unsure which task a bar tracks, such as an unnamed progress bar.

Minor issues are smaller obstacles, such as value text that adds nothing to the number.

The `aria-owns` check and the check on where the role sits carry no severity: Evinced reports them as general and sanity checks.

## Related Patterns

-   [Meter](https://knowledge.evinced.com/web/ui-patterns/meter): a measurement within a known range, such as disk usage, rather than progress through a task
-   [Slider](https://knowledge.evinced.com/web/ui-patterns/slider): a value in a range that users set themselves

## Recommended Reading

-   [progressbar role | W3C WAI-ARIA](https://www.w3.org/TR/wai-aria-1.3/#progressbar)
-   [Communicating Value and Limits for Range Widgets | W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/practices/range-related-properties/)
-   [`aria-valuenow` property | W3C WAI-ARIA](https://www.w3.org/TR/wai-aria-1.3/#aria-valuenow)
-   [`<progress>`: The Progress Indicator element | MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/progress)
-   [ARIA: progressbar role | MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role)
