Rôle Widget

`progressbar`

Marque un élément comme indicateur de progression. Utilisez <progress> en premier — il fournit la sémantique, le visuel déterminé et les attributs de valeur nativement. Recourez à role="progressbar" uniquement lorsque vous devez styliser au-delà de ce que l'élément natif permet.

Quand l’utiliser

Utilisez <progress value="42" max="100">. L’élément natif est difficile à styliser de manière cohérente entre les navigateurs, ce qui est la principale raison de recourir à role="progressbar" sur une <div> personnalisée.

Deux variantes :

Déterminé — vous connaissez le total. Définissez aria-valuemin, aria-valuemax et mettez à jour aria-valuenow au fur et à mesure de la progression.
Indéterminé — vous ne connaissez pas le total. Omettez aria-valuenow (ou ne le définissez pas). Le lecteur d’écran annonce « occupé » / « chargement » sans pourcentage.

Définissez aria-valuetext lorsque le nombre brut n’est pas significatif — par exemple, aria-valuetext="Uploading photo 3 of 8" est plus clair que « 37 pourcent ».

Une barre de progression n’est PAS une région active — les lecteurs d’écran n’annoncent pas chaque changement d’aria-valuenow. Si vous avez besoin que le changement soit annoncé, utilisez également role="status" sur un élément compagnon avec le texte de progression lisible par l’humain.

Échecs courants

role="progressbar" sur un indicateur rotatif sans aria-label. Le rôle est annoncé mais il n’y a pas de nom pour la tâche.
Utiliser role="progressbar" pour un indicateur indéterminé ET définir aria-valuenow="0". Cela annonce « 0 pourcent terminé » indéfiniment.
Oublier de supprimer la barre de progression (ou son aria-busy) lorsque le travail est terminé. Certains lecteurs d’écran continuent d’interroger l’élément.
Associer une barre de progression à un pourcentage masqué visuellement sans mettre à jour l’un ou l’autre lorsque le téléchargement se bloque. Les utilisateurs se retrouvent dans un état figé sans annonce.
Placer role="progressbar" à la fois sur le conteneur enveloppant ET sur la barre de remplissage interne. Rôles dupliqués ; choisissez l’un des deux.

Exemple

<!-- Préféré -->
<label for="upload">Uploading</label>
<progress id="upload" value="42" max="100">42%</progress>

<!-- Déterminé personnalisé -->
<div id="uploadLabel">Uploading photo 3 of 8</div>
<div
  role="progressbar"
  aria-labelledby="uploadLabel"
  aria-valuemin="0"
  aria-valuemax="100"
  aria-valuenow="37"
></div>