aria-describedby

Quando usarlo

Per informazioni supplementari posizionate accanto a un controllo: un suggerimento sul formato sotto un campo data («GG/MM/AAAA»), un elenco di requisiti per la password, un messaggio di errore inline, le istruzioni sopra un widget complesso. L’etichetta risponde a che cos’è questo?; la descrizione risponde a c’è altro che è necessario sapere?.

Va usato su input di form, pulsanti, finestre di dialogo e qualsiasi widget personalizzato in cui del contesto aggiuntivo deve seguire il nome.

Come si comporta

Il valore è un elenco di ID di elementi separati da spazio, nella stessa forma di aria-labelledby. Gli screen reader annunciano la descrizione dopo il nome accessibile e il role, di solito dopo una breve pausa — «Email, campo di testo, Vi contatteremo solo riguardo a questo ordine.» Gli ID multipli vengono concatenati nell’ordine in cui sono elencati.

La descrizione non è il nome. Non compare nel campo name dell’albero di accessibilità, quindi axe-core non la conterà come etichetta del controllo. Se il controllo non ha un nome, aria-describedby non può compensarne l’assenza.

Se la descrizione cambia (ad esempio compare un errore), occorre aggiornare il contenuto testuale dell’elemento referenziato anziché sostituire il valore di aria-describedby — molte tecnologie assistive non riannunciano quando l’attributo stesso cambia, ma riannunciano quando il testo referenziato fa parte di una live region o quando il focus entra nuovamente nel campo.

Errori comuni

• Usare aria-describedby per quello che dovrebbe essere il nome. Il controllo non ha ancora un’etichetta; l’utente sente la descrizione ma mai il nome.
• Puntare a un ID che non esiste o che è stato rimosso dal DOM da un render.
• Aggiungere aria-describedby a un elemento non focalizzabile. La maggior parte dei browser espone la descrizione solo quando l’elemento riceve il focus o viene interrogato direttamente.
• Usare lunghi testi promozionali come descrizione — gli annunci prolissi spingono gli utenti a disabilitare le descrizioni a livello globale.
• Dimenticare di associare gli errori inline dei form. aria-describedby="email-error" insieme a aria-invalid="true" è il pattern canonico; senza il riferimento, l’errore è visibile ma silenzioso.
• Riutilizzare lo stesso ID di descrizione per molti campi con aria-describedby="hint" — funziona, ma è necessario verificare che lo stesso testo si applichi effettivamente a ogni campo.

Esempio

<label for="password">Password</label>
<input
  id="password"
  type="password"
  aria-describedby="pw-rules pw-error"
  aria-invalid="true"
>
<p id="pw-rules">At least 12 characters, including a number.</p>
<p id="pw-error">Password is too short.</p>