Ruoli, stati e proprietà ARIA

Una live region che trasmette un messaggio urgente e sensibile al tempo. Gli screen reader lo annunciano immediatamente, interrompendo il parlato in corso. Da usare con parsimonia — riservare a errori e avvertimenti genuini; l'abuso causa affaticamento da tecnologia assistiva.

Un dialog che trasmette un messaggio urgente e richiede una risposta dell'utente. Combina la semantica del dialog con l'annuncio dell'alert. Da usare solo per conferme distruttive, errori che bloccano l'operatività o altre interruzioni che non possono attendere.

Contrassegna una composizione autonoma che potrebbe stare da sola — un post di blog, una notizia, una risposta in un forum o una scheda prodotto. Si consiglia di usare prima l'elemento nativo <article>; si ricorre a role="article" solo quando non è possibile utilizzare l'elemento HTML.

HTML nativo: <article>

Il landmark di intestazione a livello di sito — contiene tipicamente il logo, la navigazione principale e la ricerca. L'elemento <header> di primo livello porta questo ruolo automaticamente. È consentito un solo banner per pagina.

HTML nativo: <header> (top-level)

Contrassegna un elemento come pulsante — un controllo che attiva un'azione quando viene azionato. È preferibile utilizzare l'elemento HTML nativo <button>; ricorrere a role="button" su un <div> o uno <span> soltanto quando non è possibile usare l'elemento nativo.

HTML nativo: <button>

Contrassegna un elemento come checkbox a due o tre stati. Utilizzare prima <input type="checkbox">; ricorrere a role="checkbox" soltanto quando non è possibile usare l'input nativo — ad esempio per costruire un controllo tri-stato che deve mostrare un valore misto.

HTML nativo: <input type="checkbox">

Contrassegna un campo di testo abbinato a un elenco popup di valori — utilizzato per il completamento automatico, la ricerca predittiva e i select personalizzati. L'elemento nativo <select> copre la selezione singola; usare role="combobox" solo quando servono filtro, rendering personalizzato o suggerimenti remoti.

HTML nativo: <select>

Un landmark per i contenuti che supportano il contenuto principale ma hanno senso anche da soli — barre laterali, riquadri di articoli correlati, callout supplementari. L'elemento <aside> assume questo ruolo quando si trova al livello principale.

HTML nativo: <aside>

Il landmark footer a livello di sito — copyright, contatti, link legali. L'elemento <footer> di primo livello assume automaticamente questo ruolo. Un solo contentinfo per pagina.

HTML nativo: <footer> (top-level)

Contrassegna un elemento come definizione di un termine. Va abbinato a role="term" (o al nativo <dfn>) per associare il termine alla sua definizione. Usare prima gli elementi nativi <dl>/<dt>/<dd> o <dfn> — portano già con sé la semantica necessaria.

HTML nativo: <dfn>

Contrassegna un contenitore come finestra di dialogo modale o non modale. Si consiglia di utilizzare l'elemento nativo <dialog> con showModal() — gestisce gratuitamente il trapping del focus, il top-layer e la chiusura con Escape. Si ricorra a role="dialog" solo quando l'elemento nativo è impossibile da impiegare.

HTML nativo: <dialog>

Individua un blocco illustrativo autonomo — immagine, diagramma, listato di codice — tipicamente abbinato a una didascalia. Si usa prima l'elemento nativo <figure>; si ricorre a role="figure" solo quando l'elemento ospite non può essere un <figure>.

HTML nativo: <figure>

Un landmark per un modulo — un insieme di controlli di input che inviano dati. Un elemento <form> viene esposto come landmark form SOLO quando dispone di un nome accessibile. Senza nome, è semplicemente un modulo, non un landmark.

HTML nativo: <form aria-label>

Individua un raggruppamento generico di elementi correlati. Semanticamente meno rilevante di un landmark — i screen reader non elencano i group nel menu dei landmark. Si usa <fieldset> + <legend> per raggruppare controlli di modulo; si ricorre a role="group" per raggruppamenti non relativi a moduli.

HTML nativo: <fieldset>

Contrassegna un elemento come intestazione. Si preferisce sempre <h1>–<h6>, che trasmettono la semantica corretta e il livello appropriato senza ulteriori attributi. Si ricorre a role="heading" solo quando è necessario promuovere un elemento che non può essere un <h*>.

HTML nativo: <h1> – <h6>

Contrassegna un elemento come collegamento ipertestuale — un controllo che, se attivato, porta a una nuova risorsa. Si consiglia di usare prima l'elemento HTML nativo <a href>; si ricorre a role="link" su uno <span> o un <div> solo quando non è possibile usare l'elemento nativo.

HTML nativo: <a href>

Contrassegna un elemento come elenco di voci. Si consiglia di usare prima <ul>, <ol> o <dl> — gli elementi nativi gestiscono il role, il conteggio e il marcatore visivo. Si ricorre a role="list" solo quando la proprietà CSS list-style: none attiva la rimozione del role di elenco da parte di Safari.

HTML nativo: <ul> / <ol>

Segna un elemento come elenco di opzioni selezionabili. Per il caso semplice si utilizza <select>, che offre supporto tastiera e mobile nativo. Si ricorre a role="listbox" quando è necessario uno stile personalizzato, una selezione multipla con rendering su misura o l'abbinamento a una combobox.

HTML nativo: <select> (selezione singola)

Segna un elemento come voce di un elenco. Si utilizza <li> all'interno di <ul> o <ol> — l'elemento nativo porta già il role e la posizione nell'insieme. Si ricorre a role="listitem" solo in abbinamento a un esplicito role="list" su un elemento padre non nativo.

HTML nativo: <li>

Il landmark del contenuto principale — il contenuto primario della pagina, esclusi intestazioni, navigazione e footer ripetuti. L'elemento <main> porta questo ruolo automaticamente. Esattamente un main per pagina.

HTML nativo: <main>

Contrassegna un contenitore come menu applicativo — il popup dei menu in stile File/Modifica o i menu contestuali. Non esiste un equivalente HTML. La lista di navigazione di un sito NON è un menu; si utilizzi <nav> con <ul> di link.

Contrassegna un contenitore come menubar persistente — la striscia orizzontale sempre visibile dei menu in stile File/Modifica/Visualizza delle applicazioni desktop. Distinto da menu, che è un popup. Quasi mai il pattern corretto sul web.

Contrassegna un elemento come voce azionabile all'interno di un menu o menubar. Non esiste un equivalente HTML — i menu sono un costrutto esclusivo di ARIA. Si utilizzi questo ruolo solo quando si sta costruendo un menu applicativo vero e proprio; un semplice elenco di navigazione NON dovrebbe usare menu/menuitem.

Un landmark che raggruppa un insieme di link di navigazione — nav principale, breadcrumb, indice dei contenuti. L'elemento <nav> porta questo ruolo automaticamente. Più nav per pagina sono comuni e accettabili, ma ciascuno deve avere un nome accessibile distinto.

HTML nativo: <nav>

Contrassegna un elemento come voce selezionabile all'interno di un listbox. Un option DEVE essere un discendente di un listbox (direttamente, o tramite aria-owns). Si utilizzi il nativo <option> dentro <select>; si ricorre a role="option" solo quando si costruisce un listbox personalizzato o un popup di combobox.

HTML nativo: <option>

Contrassegna un elemento come indicatore di avanzamento. Si preferisca <progress> — fornisce la semantica, il visual determinato e gli attributi di valore nativamente. Si ricorra a role="progressbar" solo quando è necessario uno stile non consentito dall'elemento nativo.

HTML nativo: <progress>

Contrassegna un elemento come opzione singola in un gruppo mutuamente esclusivo. Un radio deve trovarsi all'interno di un radiogroup (o di un fieldset nativo). Si usi <input type="radio"> in via prioritaria; si ricorra a role="radio" solo quando l'input nativo non è praticabile.

HTML nativo: <input type="radio">

Un landmark generico per contenuti che non rientrano in banner, main, navigation, complementary o contentinfo — ma che sono comunque abbastanza importanti da giustificare la navigazione diretta. Un <section> diventa un landmark region quando, e solo quando, ha un nome accessibile.

HTML nativo: <section aria-label>

Un landmark che raggruppa un modulo di ricerca. Consente agli utenti di screen reader di raggiungere direttamente la ricerca del sito. L'elemento nativo <search> (HTML 2024) assegna automaticamente questo ruolo; per una compatibilità browser più ampia, utilizzare role="search" su un <form>.

HTML nativo: <search>

Contrassegna un elemento come campo di testo destinato a un'attività di ricerca. Preferire <input type="search">, che offre semantica nativa e pulsante di svuotamento senza configurazioni aggiuntive. Ricorrere a role="searchbox" solo per un campo di ricerca personalizzato basato su contenteditable.

HTML nativo: <input type="search">

Segna un elemento come divisore tra sezioni di contenuto o voci di un widget composito. Utilizzare prima <hr> per le interruzioni tematiche nella prosa; ricorrere a role="separator" quando si separano voci all'interno di un menu, di una toolbar o di un altro widget.

HTML nativo: <hr>

Segna un elemento come input che seleziona un valore da un intervallo. Utilizzare prima <input type="range">; ricorrere a role="slider" solo quando si necessita di una traccia personalizzata — ad esempio un selettore di intervallo a due cursori, che il nativo non supporta.

HTML nativo: <input type="range">

Una live region che trasmette informazioni consultive non urgenti. Gli screen reader annunciano le modifiche in modo «polite» — alla prossima pausa nel parlato, senza interrompere. Da usare per conferme di routine, conteggi e aggiornamenti di avanzamento. L'elemento nativo <output> porta questo ruolo.

HTML nativo: <output>

Contrassegna un elemento come interruttore on/off. Funzionalmente simile a una checkbox, ma annunciato come "switch, on" o "switch, off" anziché "checked" — si adatta meglio a un'opzione di attivazione nelle impostazioni. Non esiste ancora un equivalente HTML nativo.

Contrassegna un elemento come una scheda in un'interfaccia a schede. Un tab DEVE trovarsi all'interno di un tablist e DOVREBBE riferirsi al proprio tabpanel associato tramite aria-controls. Non esiste un elemento HTML nativo per le schede — il pattern tab è esclusivamente ARIA.

Contrassegna un contenitore come la barra delle schede in un'interfaccia a schede. Contiene elementi figli con role="tab". Le schede e i tabpanel sono un pattern esclusivamente ARIA — non esiste un equivalente HTML nativo.

Contrassegna il pannello dei contenuti associato a una scheda. Ogni tabpanel è etichettato dalla propria scheda tramite aria-labelledby; la scheda fa riferimento al pannello tramite aria-controls. Si visualizza un pannello alla volta; gli altri vengono nascosti con l'attributo hidden.

Contrassegna un elemento come campo di testo a riga singola o multipla. Utilizzare prima <input type="text"> o <textarea> — gestiscono gratuitamente ogni comportamento del textbox. Ricorrere a role="textbox" solo quando si costruisce un editor di testo avanzato su un elemento contenteditable.

HTML nativo: <input type="text"> / <textarea>

Contrassegna un contenitore come barra degli strumenti — un insieme raggruppato di controlli correlati (una barra di formattazione, una riga di pulsanti icona). Riduce il costo in termini di tab-stop: una barra degli strumenti con 10 pulsanti diventa un unico tab-stop, con i tasti freccia per spostarsi tra i pulsanti.

Contrassegna un elemento come contenitore gerarchico di treeitem — un file explorer, categorie annidate o un organigramma. Navigazione a singolo tab-stop con i tasti freccia, espansione e collasso. Non esiste un equivalente HTML nativo.

Contrassegna un elemento come nodo all'interno di un albero. Un treeitem può essere espandibile (padre di altri treeitem) o terminale (foglia). Usare solo per navigatori gerarchici — esplora file, organigramma, categorie annidate — che richiedono navigazione a singola tabulazione con frecce direzionali.

Controlla se la tecnologia assistiva annuncia l'intero contenuto di una live region all'aggiornamento oppure solo la parte modificata. Il valore predefinito è "false" (solo la differenza). Si imposta "true" quando il contesto ha senso solo come frase completa.

Contrassegna una regione come in fase di aggiornamento, in modo che la tecnologia assistiva sopprima gli annunci intermedi. Impostare a "true" durante il caricamento o mentre sono in corso modifiche estese al DOM; riportare a "false" quando la regione è stabile.

Indica lo stato di selezione corrente di una checkbox, di un radio button o di una voce di menu di tipo check. Accetta i valori "true", "false" o "mixed". La checkbox HTML nativa gestisce questo automaticamente — impostarlo manualmente soltanto su widget personalizzati.

Contrassegna l'elemento che rappresenta l'elemento corrente in un insieme — la pagina attiva in una navigazione, il passo corrente in una procedura guidata, oggi in un selettore di date. Più specifico di aria-selected; va usato sui link e sugli elementi in cui la selezione non è la metafora appropriata.

Indica che un controllo è percepibile e ricevibile dal focus ma non risponde all'input dell'utente. Si preferisca l'attributo nativo HTML disabled quando disponibile; si ricorra ad aria-disabled quando è necessario che l'elemento rimanga focusable o possa ricevere un tooltip.

Indica se un elemento comprimibile — pulsante disclosure, combobox, menu, treeitem — è attualmente aperto. Accetta "true" o "false". Di norma è abbinato ad aria-controls che punta alla regione aperta dal controllo.

Rimuove un elemento e tutti i suoi discendenti dall'albero di accessibilità. Gli utenti vedenti continuano a visualizzare l'elemento; la tecnologia assistiva non vi accede mai. Da riservare ai contenuti decorativi; non va mai applicato a un controllo che può ricevere il focus.

Indica che un controllo di modulo non ha superato la validazione. Abbinare con aria-describedby che punta al messaggio di errore leggibile dall'utente, in modo che lo screen reader annunci sia lo stato non valido sia la motivazione.

Segna una regione i cui aggiornamenti devono essere annunciati dalla tecnologia assistiva senza spostare il focus. Per la maggior parte dei casi si sceglie «polite»; «assertive» è riservato agli aggiornamenti genuinamente urgenti. La regione deve essere presente nel DOM al momento del rendering iniziale.

Indica alle tecnologie assistive di trattare il resto della pagina come inerte mentre un dialogo è aperto. Va impostato a "true" su role="dialog" o role="alertdialog". Non rende effettivamente inerte lo sfondo — occorre abbinarlo all'attributo inert o a un focus trap.

Indica se un pulsante di alternanza è attualmente premuto. Impostato su "true" quando l'alternanza è attiva, "false" quando è disattiva; la tecnologia assistiva annuncia lo stato insieme all'etichetta.

Indica che il valore di un controllo di modulo non può essere modificato, ma il controllo resta operabile — è possibile portarvi il focus, copiarne il contenuto e inviarlo con il form. Diverso da aria-disabled, che rende il controllo inoperabile.

Indica che un elemento all'interno di un contenitore a selezione singola o multipla è attualmente selezionato. Utilizzato su ruoli come tab, option, gridcell, treeitem e simili. Distinto da aria-checked (checkbox/radio) e aria-pressed (pulsante di attivazione/disattivazione).

Su un widget composito, indica l'ID del discendente attualmente attivo. Il focus DOM rimane sul contenitore mentre un focus virtuale si sposta tra i figli. Alternativa al roving tabindex per listbox, combobox e griglie.

Su un textbox o combobox, dichiara che tipo di completamento automatico offre il controllo — suggerimenti inline, un elenco di opzioni, entrambi o nessuno. È distinto dall'attributo HTML autocomplete, che riguarda la semantica dei campi modulo per il browser.

Indica l'elemento o gli elementi la cui presenza o contenuto è governato da questo controllo. Abbinamenti comuni: un tab controlla il proprio tabpanel, un pulsante di disclosure controlla una region rivelata. Il supporto tra le tecnologie assistive è disomogeneo — si utilizzi con parsimonia.

Referenzia uno o più ID di elementi il cui testo diventa la descrizione estesa di questo elemento. Viene annunciato dopo il nome accessibile. Va usato per testo di aiuto, suggerimenti sul formato e messaggi di errore inline.

Informa la tecnologia assistiva che l'attivazione di questo controllo aprirà un popup, specificandone il tipo. Accetta "menu", "listbox", "tree", "grid", "dialog", oppure "true" / "false". Da abbinare ad aria-expanded affinché la tecnologia assistiva possa annunciare anche se il popup è aperto.

Fornisce un nome accessibile come stringa quando non è disponibile testo visibile. Si utilizza solo in assenza di un'etichetta a schermo — se esiste del testo visibile, è preferibile aria-labelledby in modo che il nome annunciato corrisponda a ciò che l'utente vede.

Fa riferimento a uno o più ID di elemento il cui testo visibile diventa il nome accessibile di questo elemento. È preferibile ad aria-label quando un testo già presente a schermo descrive il controllo.

Indica il livello gerarchico di un elemento all'interno di una struttura. Obbligatorio sugli elementi con role="heading"; utilizzato anche su role="treeitem" e role="listitem" all'interno di elenchi annidati. Valore intero, a partire da 1.

Dichiara una relazione genitore-figlio nell'albero di accessibilità quando la struttura del DOM non la esprime. Rende gli elementi referenziati figli di quello corrente ai fini dell'AT. È uno strumento avanzato — facile da usare in modo errato.

Posizione di un elemento all'interno di un insieme quando il DOM non riesce a esprimerla — tipicamente perché le voci sono virtualizzate, paginate o filtrate. Da abbinare sempre ad aria-setsize affinché gli screen reader possano annunciare «3 di 47».

Indica che l'input dell'utente è obbligatorio su un controllo prima che il form possa essere inviato. Usare l'attributo HTML required sui campi nativi; ricorrere ad aria-required solo quando non esiste un equivalente HTML — ad esempio un combobox costruito su un div.

Numero totale di elementi in un insieme quando il DOM non li contiene tutti. Si abbina a aria-posinset affinché uno screen reader possa annunciare «elemento 14 di 5.000» anche se ne vengono renderizzati solo cinque. Usare -1 se il totale è sconosciuto.

Sull'intestazione di una colonna o riga in una griglia o tabella ordinabile, annuncia la direzione di ordinamento corrente. Valori: "ascending", "descending", "other", o "none". Solo un'intestazione per volta nella tabella dovrebbe portare un valore di ordinamento attivo.

Valore numerico corrente di un widget a intervallo — slider, progressbar, spinbutton, scrollbar. Da abbinare ad aria-valuemin e aria-valuemax affinché la tecnologia assistiva possa annunciare una posizione significativa. Utilizzare aria-valuetext per etichette non numeriche.