# aria-describedby contre aria-details pour décrire un champ complexe

> Deux attributs ARIA permettent d'associer une description à un champ, mais ils ne fonctionnent pas de la même manière. Explication sur un exemple de champ de formulaire réglementaire.

- Auteur : WordPress Développement
- Publié le : 2023-04-21
- Mis à jour le : 2023-04-21
- Catégorie : Accessibilité
- URL : https://www.wpmoderne.fr/accessibilite/aria-describedby-aria-details-champ-complexe/

## L’essentiel

- aria-describedby fusionne un texte simple dans l'annonce
- aria-details pointe vers un contenu structuré, non fusionné
- Le choix dépend de la complexité de la description

La spécification WAI-ARIA distingue deux attributs qui semblent, au premier regard, remplir le même rôle : associer une description supplémentaire à un élément de formulaire. Leur usage diverge pourtant nettement dès qu'on regarde comment chacun est restitué par un lecteur d'écran. La distinction devient concrète sur un champ de formulaire réglementaire complexe, comme celui d'une déclaration fiscale en ligne où une case exige une justification détaillée avant validation.

## aria-describedby : une description fusionnée dans l'annonce

`aria-describedby` référence un ou plusieurs identifiants d'éléments dont le contenu textuel est concaténé et lu à la suite du nom accessible du champ, généralement après une courte pause. C'est l'attribut le plus courant pour associer un texte d'aide ou un message d'erreur à un champ :

```
<label for="justification">Justificatif du montant déclaré</label>
<input type="text" id="justification" aria-describedby="aide-justification">
<p id="aide-justification">
  Indiquez la référence du document joint, au format AAAA-NNNNN.
</p>
```

Un lecteur d'écran annoncera ici quelque chose comme « Justificatif du montant déclaré, modifiable, Indiquez la référence du document joint, au format AAAA-NNNNN ». Le texte référencé est traité comme une simple chaîne de caractères : toute structure (listes, titres, mise en forme) qu'il pourrait contenir est ignorée, seul le texte brut est restitué.

## aria-details : un lien vers un contenu structuré, non fusionné

> L'essentiel à retenir : aria-describedby fusionne un texte simple dans l'annonce ; aria-details pointe vers un contenu structuré, non fusionné ; Le choix dépend de la complexité de la description

`aria-details` fonctionne différemment : il ne fusionne rien dans l'annonce immédiate. Il indique qu'un élément possède des informations détaillées disponibles ailleurs, que l'utilisateur peut consulter à la demande, en conservant leur structure propre (titres, listes, tableaux). C'est l'attribut adapté quand la description dépasse une simple phrase d'aide :

```
<label for="justification">Justificatif du montant déclaré</label>
<input type="text" id="justification" aria-details="details-justification">

<div id="details-justification" role="note">
  <h3>Formats de justificatif acceptés</h3>
  <ul>
    <li>Avis d'imposition de l'année précédente</li>
    <li>Attestation employeur datée de moins de trois mois</li>
    <li>Relevé de compte faisant apparaître le montant</li>
  </ul>
</div>
```

Le lecteur d'écran signale la présence de ces détails sans les lire automatiquement, généralement par une annonce du type « a des détails », laissant l'utilisateur déclencher leur lecture par un raccourci dédié. La structure interne, ici un titre et une liste, reste intacte et navigable pour qui choisit de la consulter.

## Quand choisir l'un plutôt que l'autre

| Situation | Attribut recommandé |
| --- | --- |
| Texte d'aide court, une phrase | `aria-describedby` |
| Message d'erreur de validation | `aria-describedby` |
| Liste de formats acceptés, plusieurs points | `aria-details` |
| Renvoi vers des explications structurées longues | `aria-details` |

En pratique, la grande majorité des cas rencontrés sur un formulaire WordPress classique relève de `aria-describedby` : messages d'erreur, indications de format, compteurs de caractères restants. `aria-details` reste réservé à des cas où la description elle-même mérite une navigation propre, ce qui explique pourquoi son usage demeure rare en dehors de formulaires réglementaires ou médicaux complexes.

## Une limite de compatibilité à connaître

Le support de `aria-details` reste plus inégal selon les combinaisons de navigateurs et de lecteurs d'écran que celui, très mature, de `aria-describedby`. Avant de s'appuyer sur `aria-details` pour une information réellement indispensable à la compréhension d'un champ, un test avec les combinaisons de lecteurs d'écran effectivement utilisées par le public visé reste recommandé, faute de quoi l'information détaillée pourrait tout simplement rester invisible pour une partie des utilisateurs.

> Entre les deux attributs, le critère de choix n'est jamais la préférence de développement, mais la nature de l'information à transmettre : une phrase d'aide se fusionne, une explication structurée se consulte à part.

## Ce que cet attribut ne remplace pas

Ni `aria-describedby` ni `aria-details` ne remplacent le nom accessible d'un champ, porté par son `<label>`. Les deux attributs viennent en complément d'un nom déjà correctement établi ; utilisés seuls, sans étiquette associée, ils ne suffisent pas à rendre un champ compréhensible.

## En résumé

Retenir la distinction entre les deux attributs demande un seul repère : `aria-describedby` fusionne un texte simple dans l'annonce immédiate du champ, `aria-details` signale un contenu structuré consultable à la demande. Le choix du bon attribut dépend uniquement de la nature de l'information à transmettre, jamais d'une préférence stylistique.