aria-expanded

Quando utilizzarlo

Su qualsiasi controllo che apre e chiude un’altra regione dell’interfaccia: un’intestazione di accordion, un pulsante disclosure «mostra altro», un trigger di combobox, un menu button, un treeitem con figli, un toggle per la navigazione hamburger. Il controllo rimane lo stesso elemento in entrambi gli stati — cambia solo il valore dell’attributo.

Se il controllo commuta lo stato sull’elemento stesso (disattiva audio / riattiva audio, segui / smetti di seguire), si utilizzi invece aria-pressed. aria-expanded descrive una relazione con un’altra regione, solitamente identificata da aria-controls.

Il ruolo determina se aria-expanded è significativo: è supportato su button, combobox, link, tab, treeitem, menuitem, gridcell, row e pochi altri. Inserirlo su un <div> senza role non produce alcun effetto utile.

Come mantenerlo sincronizzato

I valori validi sono "true" (regione aperta) e "false" (regione chiusa). L’impostazione predefinita, se omesso, è «nessuno stato expanded» — il che è diverso da "false". Se il controllo è mai espandibile, si renderizzi aria-expanded="false" nello stato chiuso anziché ometterlo.

Si aggiorni l’attributo nello stesso percorso di codice che anima l’apertura o la chiusura della regione. L’attributo è la fonte di verità che leggono gli screen reader; lo chevron visivo è un segnale secondario per gli utenti vedenti.

Si abbini a aria-controls="<region-id>" affinché lo screen reader possa annunciare la relazione: «Filtri, pulsante, compresso, controlla filter-panel». Alcune tecnologie assistive offrono una scorciatoia per passare direttamente alla regione controllata.

Errori comuni

• Attivare/disattivare una classe CSS sul pannello dimenticando di aggiornare aria-expanded.
• Usare aria-expanded su un elemento non interattivo senza role. L’attributo viene ignorato.
• Aggiungere solo aria-expanded="true" — non renderizzare mai lo stato "false". Gli screen reader non annunciano nulla nello stato chiuso.
• Usare aria-expanded su un controllo che non espande effettivamente una regione (un pulsante «Invia»).
• Confondere aria-expanded con aria-pressed su pulsanti toggle che non aprono una regione separata.
• Omettere aria-controls, lasciando implicita la relazione tra trigger e pannello.

Esempio

<button
  type="button"
  aria-expanded="false"
  aria-controls="filters-panel"
  onclick="toggle(this)"
>
  Filters
</button>

<div id="filters-panel" hidden>
  <!-- filter controls -->
</div>