ARIA progressbar needs accessible name

ARIA progressbar components must have an accessible name

Every element with role=progressbar needs an accessible name that states what the progress represents.

This appears in file uploads, checkout steps, data imports, and loading indicators.

Without a clear name, screen reader and voice control users cannot tell which task a percentage refers to.

Why It Matters

Screen reader users may only hear “progress bar, 50%” with no context, making it impossible to know which operation is halfway done.

Cognitive disabilities are affected when multiple progress indicators exist and none are distinguished by purpose.

Low-vision users relying on speech output also need the label to disambiguate similar progress bars.

Common Causes

• Using a generic <div role="progressbar"> without a label.
• Empty aria-label or an aria-labelledby that points to a missing/empty element.
• Relying on visual text near the bar that is not programmatically associated.
• Dynamically injected progress bars created without names.
• Native <progress> used without a visible <label> or an accessible name.
• Depending solely on the title attribute (not reliable across assistive tech).

How to Fix

1. Provide a programmatic label:
   • Preferred for native: Use <label for> with the <progress> element.
   • For ARIA widgets: Use aria-labelledby to reference visible text.
   • If no visible label fits, use a concise aria-label.
2. Make the label specific to the task:
   • Example: “File upload progress”, “Checkout step progress”, “Report generation progress”.
   • Keep it short; avoid repeating values (e.g., do not include “50%” in the name).
3. Ensure proper value states:
   • For ARIA progressbar: set aria-valuemin, aria-valuemax, and aria-valuenow for determinate bars.
   • For indeterminate bars, omit aria-valuenow.
   • For native <progress>, use value and max attributes.
4. Avoid title-only naming:
   • Do not rely on title for the accessible name; support is inconsistent. Prefer a real label or ARIA naming.
5. Multiple progress bars:
   • Give each a unique, descriptive name so users can distinguish them.

Compliance note: This maps to WCAG 2.2 Success Criterion 4.1.2 (Name, Role, Value).

How to Test

• Keyboard check:
• If the progressbar is focusable (most are not), when focused it should expose the correct name and value to assistive tech.
• Tabbing should not trap focus. Progress bars are usually read-only.
• Screen reader check (desktop):
• NVDA/JAWS + browser: Move to the progressbar. Expect announcement like “Upload progress, progress bar, 32%”.
• Verify the task description (name) is accurate and unique if multiple bars exist.
• Mobile/touch check:
• iOS VoiceOver or Android TalkBack: Swipe to the control. Confirm it announces the purpose and current value.
• DevTools/Accessibility Tree:
• Inspect the node and confirm the Computed Name is present and correct.
• Automated checks:
• Run an accessibility scanner and confirm no “ARIA progressbar name” violations remain.

Good Example

<label for="upload-progress">File upload progress</label>
<progress id="upload-progress" value="32" max="100"></progress>

<span id="report-progress-label" class="sr-only">Report generation progress</span>
<div role="progressbar"
     aria-labelledby="report-progress-label"
     aria-valuemin="0"
     aria-valuemax="100"
     aria-valuenow="68"></div>

Bad Example

<!-- No accessible name at all -->
<div role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="45"></div>

<!-- Empty aria-label -->
<div role="progressbar" aria-label=""></div>

<!-- Broken reference -->
<div role="progressbar" aria-labelledby="missing-label"></div>

<!-- Native progress without label or ARIA name -->
<progress value="70" max="100"></progress>

Quick Checklist

• Every progressbar exposes a clear, concise accessible name describing the task.
• Use <label for> with <progress>, or aria-labelledby/aria-label for ARIA widgets.
• Do not rely on title to provide the name.
• Include appropriate value attributes (aria-valuenow/min/max or value/max).
• Names do not include dynamic numeric values.
• Each progressbar has a unique name when multiple are present.
• Confirm the Computed Name in DevTools and with at least one screen reader.