Role, stany i właściwości ARIA

Region na żywo przekazujący pilny, zależny od czasu komunikat. Czytniki ekranu ogłaszają go natychmiast, przerywając bieżącą mowę. Używaj oszczędnie — rezerwuj dla prawdziwych błędów i ostrzeżeń; nadużycie powoduje zmęczenie technologią asystującą.

Okno dialogowe przekazujące pilny komunikat i wymagające odpowiedzi użytkownika. Łączy semantykę okna dialogowego z ogłoszeniem alertu. Używaj tylko dla destrukcyjnych potwierdzeń, błędów blokujących dalszą pracę lub innych przerwań, które nie mogą czekać.

Oznacza samodzielną kompozycję, która mogłaby istnieć osobno — wpis na blogu, artykuł informacyjny, odpowiedź na forum lub karta produktu. Najpierw użyj natywnego elementu <article>; sięgaj po role="article" tylko gdy nie możesz użyć elementu HTML.

Natywny HTML: <article>

Punkt orientacyjny nagłówka całej witryny — zazwyczaj zawiera logo, główną nawigację i wyszukiwarkę. Element <header> na najwyższym poziomie automatycznie przyjmuje tę rolę. Na jednej stronie może być tylko jeden banner.

Natywny HTML: <header> (top-level)

Oznacza element jako przycisk — kontrolkę wyzwalającą akcję po aktywacji. Najpierw użyj natywnego elementu HTML <button>; sięgaj po role="button" na <div> lub <span> tylko wtedy, gdy nie ma możliwości użycia elementu natywnego.

Natywny HTML: <button>

Oznacza element jako pole wyboru o dwóch lub trzech stanach. Najpierw użyj <input type="checkbox">; sięgaj po role="checkbox" tylko wtedy, gdy nie możesz użyć natywnego elementu — na przykład przy budowaniu kontrolki tri-state, która musi pokazywać wartość mieszaną.

Natywny HTML: <input type="checkbox">

Oznacza pole tekstowe połączone z wyskakującą listą wartości — do autouzupełniania, wyszukiwania z podpowiedziami i niestandardowych list wyboru. Natywny <select> obsługuje prosty wybór; sięgaj po role="combobox" tylko gdy potrzebujesz filtrowania, niestandardowego renderowania lub zdalnych sugestii.

Natywny HTML: <select>

Punkt orientacyjny dla treści wspierającej zawartość główną, lecz sensownej samodzielnie — paska boczne, bloki powiązanych artykułów, dodatkowe ramki informacyjne. Element <aside> przyjmuje tę rolę, gdy znajduje się na najwyższym poziomie.

Natywny HTML: <aside>

Punkt orientacyjny stopki całej witryny — prawa autorskie, dane kontaktowe, linki prawne. Najwyższy poziom elementu <footer> przyjmuje tę rolę automatycznie. Na stronie może wystąpić tylko jeden contentinfo.

Natywny HTML: <footer> (top-level)

Oznacza element jako definicję terminu. Stosuj w parze z role="term" (lub natywnym <dfn>), aby powiązać termin z jego definicją. W pierwszej kolejności używaj natywnych <dl>/<dt>/<dd> lub <dfn> — przenoszą semantykę bez ARIA.

Natywny HTML: <dfn>

Oznacza kontener jako modalne lub niemodalne okno dialogowe. Zalecane jest użycie natywnego elementu <dialog> z showModal() — obsługuje on pułapkę fokusa, warstwę najwyższą, tło i zamknięcie przez Escape bez dodatkowego kodu. Po role="dialog" sięgaj tylko gdy natywny element jest niemożliwy do zastosowania.

Natywny HTML: <dialog>

Oznacza samodzielny blok ilustracyjny — obraz, diagram, fragment kodu — zazwyczaj z podpisem. Najpierw użyj natywnego elementu <figure>; po role="figure" sięgaj tylko gdy element hosta nie może być <figure>.

Natywny HTML: <figure>

Punkt orientacyjny dla formularza — zbioru kontrolek wejściowych przesyłających dane. Element <form> jest eksponowany jako punkt orientacyjny formularza TYLKO gdy ma dostępną nazwę. Bez nazwy jest po prostu formularzem, nie punktem orientacyjnym.

Natywny HTML: <form aria-label>

Oznacza ogólne grupowanie powiązanych elementów. Mniej semantycznie ciężki niż punkt orientacyjny — czytniki ekranu nie wymieniają grup w menu punktów orientacyjnych. Użyj <fieldset> + <legend> dla zgrupowanych kontrolek formularza; po role="group" sięgaj dla grupowań spoza formularza.

Natywny HTML: <fieldset>

Oznacza element jako nagłówek. W pierwszej kolejności używaj znaczników <h1>–<h6> — niosą właściwą semantykę i poprawny poziom bez dodatkowej pracy. Po role="heading" sięgaj tylko wtedy, gdy nie możesz użyć natywnego elementu nagłówkowego.

Natywny HTML: <h1> – <h6>

Oznacza element jako hiperłącze — kontrolkę, która po aktywacji nawiguje do nowego zasobu. Najpierw używaj natywnego elementu HTML <a href>; sięgaj po role="link" na <span> lub <div> tylko gdy nie ma możliwości użycia natywnego elementu.

Natywny HTML: <a href>

Oznacza element jako listę pozycji. Najpierw używaj <ul>, <ol> lub <dl> — natywne elementy obsługują rolę, licznik i znacznik wizualny. Sięgaj po role="list" tylko gdy CSS list-style: none wyzwala usunięcie roli listy przez Safari.

Natywny HTML: <ul> / <ol>

Oznacza element jako listę wybieralnych opcji. Używaj <select> w prostym przypadku jednokrotnego wyboru — zapewnia przyjazny mobilnie selektor i pełną obsługę klawiatury. Sięgaj po role="listbox" gdy potrzebujesz niestandardowego stylowania, wielokrotnego wyboru lub parowania z comboboxem.

Natywny HTML: <select> (single-select)

Oznacza element jako jedną pozycję na liście. Używaj <li> wewnątrz <ul> lub <ol> — natywny element niesie rolę i pozycję w zbiorze. Sięgaj po role="listitem" tylko gdy parowany jest z jawnym role="list" na elemencie niebędącym listą.

Natywny HTML: <li>

Punkt orientacyjny głównej treści strony — zawartość unikalna dla bieżącej strony, z wyłączeniem powtarzających się nagłówków, nawigacji i stopek. Element <main> przyjmuje tę rolę automatycznie. Na stronie może wystąpić dokładnie jeden main.

Natywny HTML: <main>

Oznacza kontener jako menu aplikacji — wyskakujące menu w stylu Plik/Edycja lub menu kontekstowe. Nie ma odpowiednika w HTML. Lista nawigacyjna serwisu NIE jest menu; zamiast niej użyj <nav> z listą <ul> zawierającą łącza.

Oznacza kontener jako stały pasek menu — zawsze widoczny poziomy pasek w stylu Plik/Edycja/Widok znany z aplikacji desktopowych. Różni się od menu, które jest wyskakujące. W zastosowaniach webowych niemal nigdy nie jest właściwym wzorcem.

Oznacza element jako wykonywalną pozycję wewnątrz menu lub paska menu. Nie ma odpowiednika w HTML — menu to konstrukcja wyłącznie ARIA. Stosuj tę rolę tylko podczas budowania rzeczywistego menu (w stylu aplikacji); zwykła lista nawigacyjna NIE powinna używać menu/menuitem.

Punkt orientacyjny grupujący zestaw łączy nawigacyjnych — nawigacja główna, ścieżka nawigacyjna, spis treści. Element <nav> przyjmuje tę rolę automatycznie. Wiele elementów nav na stronie jest typowe i dozwolone, ale każdy musi mieć unikalną dostępną nazwę.

Natywny HTML: <nav>

Oznacza element jako wybieralną pozycję wewnątrz listbox. Opcja MUSI być potomkiem listbox (bezpośrednio lub przez aria-owns). Używaj natywnego <option> w <select>; po role="option" sięgaj tylko przy budowaniu własnego listbox lub okna podręcznego combobox.

Natywny HTML: <option>

Oznacza element jako wskaźnik postępu. Najpierw użyj <progress> — dostarcza semantykę, determistyczny wygląd i atrybuty wartości natywnie. Po role="progressbar" sięgaj tylko wtedy, gdy musisz ostylować element poza możliwości elementu natywnego.

Natywny HTML: <progress>

Oznacza element jako pojedynczą opcję w grupie wzajemnie wykluczających się wyborów. Przycisk radiowy musi znajdować się wewnątrz radiogroup (lub natywnego fieldset). Najpierw użyj <input type="radio">; po role="radio" sięgaj tylko wtedy, gdy natywny input jest niemożliwy.

Natywny HTML: <input type="radio">

Ogólny punkt orientacyjny dla treści, która nie pasuje do banner, main, navigation, complementary ani contentinfo — ale jest wystarczająco ważna, by do niej nawigować. Element <section> staje się punktem orientacyjnym region wtedy i tylko wtedy, gdy ma dostępną nazwę.

Natywny HTML: <section aria-label>

Punkt orientacyjny grupujący formularz wyszukiwania. Umożliwia użytkownikom czytników ekranu bezpośrednie przejście do wyszukiwarki serwisu. Natywny element <search> (HTML 2024) automatycznie pełni tę rolę; dla szerszego wsparcia przeglądarek należy dziś używać role="search" na elemencie <form>.

Natywny HTML: <search>

Oznacza element jako pole tekstowe przeznaczone do wyszukiwania. Używaj <input type="search"> — dostarcza affordance czyszczenia i semantykę wyszukiwania bezpłatnie. Po role="searchbox" sięgaj tylko dla niestandardowego pola wyszukiwania opartego na contenteditable.

Natywny HTML: <input type="search">

Oznacza element jako separator między sekcjami treści lub elementami w złożonym widżecie. Najpierw użyj <hr> dla tematycznych przerw w tekście; sięgaj po role="separator" do oddzielania elementów w menu, pasku narzędzi lub innym widżecie.

Natywny HTML: <hr>

Oznacza element jako kontrolkę wybierającą wartość z zakresu. Najpierw użyj <input type="range">; sięgaj po role="slider" tylko gdy potrzebujesz własnego toru — na przykład dla suwaka z dwoma uchwytami, którego natywny element nie obsługuje.

Natywny HTML: <input type="range">

Region na żywo przekazujący nieistotne informacje doradcze. Czytniki ekranu ogłaszają zmiany grzecznie — przy najbliższej przerwie w mowie, bez przerywania. Używaj do rutynowych potwierdzeń, liczników i komunikatów o postępie. Natywny element <output> posiada tę rolę.

Natywny HTML: <output>

Oznacza element jako przełącznik włącz/wyłącz. Funkcjonalnie zbliżony do pola wyboru, ale ogłaszany jako „przełącznik, włączony" lub „przełącznik, wyłączony" zamiast „zaznaczony" — lepiej pasuje do przełącznika ustawień. Nie ma jeszcze natywnego odpowiednika HTML.

Oznacza element jako jeden tab w interfejsie z kartami. Tab MUSI znajdować się wewnątrz tablist i POWINIEN wskazywać powiązany tabpanel przez aria-controls. Nie istnieje natywny element HTML dla kart — wzorzec ten oparty jest wyłącznie na ARIA.

Oznacza kontener jako pasek kart w interfejsie zakładkowym. Przechowuje elementy potomne role="tab". Karty i tabpanel to wzorzec oparty wyłącznie na ARIA — nie istnieje natywny element HTML tablist.

Oznacza panel treści powiązany z kartą. Każdy tabpanel jest etykietowany przez swój tab przez aria-labelledby; tab wskazuje panel przez aria-controls. Wyświetlaj jeden panel jednocześnie; pozostałe ukrywaj atrybutem hidden.

Oznacza element jako jednoliniowe lub wieloliniowe pole tekstowe. W pierwszej kolejności używaj <input type="text"> lub <textarea> — obsługują one wszystkie zachowania pola tekstowego. Po role="textbox" sięgaj wyłącznie przy budowaniu edytora tekstu sformatowanego na elemencie contenteditable.

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

Oznacza kontener jako pasek narzędzi — zgrupowany zestaw powiązanych kontrolek (pasek formatowania, rząd przycisków ikony). Zmniejsza koszt tabulacji: pasek 10 przycisków staje się jednym punktem tabulacji, a strzałki służą do poruszania się między przyciskami.

Oznacza element jako hierarchiczny kontener elementów treeitem — eksplorator plików, zagnieżdżone kategorie lub schemat organizacyjny. Jeden punkt tabulacji, nawigacja strzałkami, zwijanie i rozwijanie. Nie istnieje natywny odpowiednik w HTML.

Oznacza element jako węzeł wewnątrz drzewa. treeitem może być rozwijalny (rodzic kolejnych węzłów) lub końcowy (liść). Stosuj wyłącznie przy budowie hierarchicznego nawigatora — eksploratora plików, schematu organizacyjnego, zagnieżdżonych kategorii — z nawigacją strzałkami i jednym punktem tabulacji.

Kontroluje, czy technologia asystująca ogłasza całą zawartość regionu na żywo przy aktualizacji, czy tylko zmienioną część. Domyślnie „false" (tylko różnica). Ustaw „true", gdy kontekst ma sens wyłącznie jako całe zdanie.

Oznacza region jako będący w trakcie aktualizacji, dzięki czemu technologie wspomagające wstrzymują tymczasowe komunikaty. Ustaw na „true" podczas ładowania lub gdy trwają duże zmiany w DOM; przełącz z powrotem na „false", gdy region jest stabilny.

Wskazuje bieżący stan zaznaczenia pola wyboru, przycisku radio lub elementu menu w stylu checkboxa. Przyjmuje wartości „true", „false" lub „mixed". Natywny checkbox HTML zarządza tym automatycznie — ustawiaj ręcznie tylko na niestandardowych widżetach.

Oznacza element reprezentujący bieżącą pozycję w zbiorze — aktywną stronę w nawigacji, bieżący krok w kreatorze, dzisiejszą datę w wybieraku dat. Bardziej precyzyjny niż aria-selected; stosuj na linkach i elementach, gdzie selekcja nie jest właściwą metaforą.

Wskazuje, że kontrolka jest percepcyjna i fokusowalna, ale nie reaguje na interakcję użytkownika. Preferuj natywny atrybut HTML disabled gdy jest dostępny; po aria-disabled sięgaj gdy element musi pozostać fokusowany lub może wyświetlać podpowiedź.

Wskazuje, czy element zwijaný — przycisk ujawniający, combobox, menu, treeitem — jest aktualnie otwarty. Przyjmuje wartości "true" lub "false". Zazwyczaj łączony z aria-controls wskazującym na region, który kontrolka otwiera.

Usuwa element i wszystkich jego potomków z drzewa dostępności. Użytkownicy widzący nadal widzą element; technologia wspomagająca nigdy do niego nie dociera. Stosuj wyłącznie dla treści dekoracyjnych; nigdy nie nakładaj na element, który może otrzymać fokus.

Wskazuje, że element sterujący formularza nie przeszedł walidacji. Łącz z aria-describedby wskazującym na komunikat błędu w czytelnym języku, by czytnik ekranu ogłosił zarówno stan błędu, jak i jego przyczynę.

Oznacza region, którego aktualizacje powinny być ogłaszane przez technologię asystującą bez przenoszenia fokusu. Wybierz "polite" w większości przypadków, "assertive" dla naprawdę pilnych aktualizacji. Region musi być w DOM przy początkowym renderowaniu.

Informuje technologie wspomagające, że reszta strony jest nieaktywna podczas otwarcia okna dialogowego. Ustaw na „true" dla role="dialog" lub role="alertdialog". Nie czyni tła faktycznie nieaktywnym — połącz z atrybutem inert lub pułapką fokusu.

Wskazuje, czy przycisk przełączający jest aktualnie wciśnięty. Ustaw „true", gdy przełącznik jest włączony, „false", gdy wyłączony; technologia wspomagająca ogłasza stan razem z etykietą.

Wskazuje, że wartości kontrolki formularza nie można edytować, ale kontrolka pozostaje operatywna — można ją sfokusować, skopiować jej treść i zostaje ona przesłana wraz z formularzem. Różni się od aria-disabled, który czyni kontrolkę nieooperatywną.

Wskazuje, że element wewnątrz kontenera z modelem jednokrotnego lub wielokrotnego wyboru jest aktualnie zaznaczony. Używany na rolach tab, option, gridcell, treeitem i podobnych. Różni się od aria-checked (pole wyboru/przycisk radiowy) i aria-pressed (przycisk przełączający).

W złożonym widżecie wskazuje ID aktywnego potomka. Fokus DOM pozostaje na kontenerze, podczas gdy wirtualny fokus przemieszcza się po elementach potomnych. Alternatywa dla roving tabindex w listboxach, comboboxach i gridach.

Na polu tekstowym lub comboboxie deklaruje rodzaj autouzupełniania oferowanego przez formant — sugestie wbudowane, lista opcji, obie lub żadna. Różni się od atrybutu HTML autocomplete, który dotyczy semantyki pól formularza dla przeglądarki.

Wskazuje element lub elementy, których zawartością lub widocznością zarządza dany kontrolka. Typowe pary: zakładka steruje swoim tabpanel, przycisk ujawniania steruje odsłanianym regionem. Obsługa przez technologie wspomagające jest nierówna — stosuj oszczędnie.

Odwołuje się do identyfikatorów jednego lub więcej elementów, których tekst staje się rozszerzonym opisem tego elementu. Ogłaszany po dostępnej nazwie. Używaj dla tekstu pomocniczego, wskazówek dotyczących formatu i komunikatów błędów wyświetlanych inline.

Informuje technologie wspomagające, że aktywowanie danego elementu sterującego otworzy wyskakujące okno, i określa jego typ. Przyjmuje wartości „menu", „listbox", „tree", „grid", „dialog" lub „true" / „false". Łącz z aria-expanded, by AT mogło ogłaszać, czy wyskakujące okno jest otwarte.

Dostarcza dostępną nazwę jako ciąg znaków, gdy nie ma widocznego tekstu. Używaj tylko wtedy, gdy na ekranie nie ma etykiety — jeśli widoczny tekst istnieje, preferuj aria-labelledby, by wypowiadana nazwa zgadzała się z tym, co użytkownik widzi.

Odwołuje się do jednego lub więcej identyfikatorów elementów, których widoczny tekst staje się dostępną nazwą tego elementu. Preferowane względem aria-label, gdy tekst na ekranie już opisuje element sterujący.

Wskazuje hierarchiczny poziom elementu w strukturze. Wymagany na elementach role="heading"; stosowany też na role="treeitem" i role="listitem" w zagnieżdżonych listach. Wartość całkowita, zaczynając od 1.

Deklaruje relację rodzic-dziecko w drzewie dostępności, gdy struktura DOM jej nie wyraża. Przenoszone węzły stają się dziećmi elementu właściciela w widoku technologii wspomagających. Potężne narzędzie — łatwe w nadużyciu.

Pozycja elementu w zbiorze, gdy DOM nie może jej wyrazić — zazwyczaj gdy pozycje są wirtualizowane, stronicowane lub filtrowane. Zawsze łącz z aria-setsize, żeby czytniki ekranu mogły ogłaszać „3 z 47".

Wskazuje, że dane wprowadzone przez użytkownika są wymagane w kontrolce przed przesłaniem formularza. Na natywnych polach formularza należy używać atrybutu HTML required; po aria-required należy sięgać tylko wtedy, gdy nie istnieje odpowiednik HTML — np. dla combobox zbudowanego na elemencie div.

Łączna liczba elementów w zestawie, gdy DOM nie zawiera ich wszystkich. Działa w parze z aria-posinset, dzięki czemu czytnik ekranu może ogłosić „element 14 z 5000", nawet jeśli wyrenderowano tylko pięć. Użyj -1, jeśli łączna liczba jest nieznana.

Na nagłówku kolumny lub wiersza w sortowalnej siatce lub tabeli ogłasza bieżący kierunek sortowania. Wartości: "ascending", "descending", "other" lub "none". Tylko jeden nagłówek w tabeli powinien jednocześnie mieć wartość wskazującą sortowanie.

Bieżąca wartość liczbowa widżetu zakresu — suwaka, paska postępu, spinbuttona, paska przewijania. Łącz z aria-valuemin i aria-valuemax, aby technologie asystujące mogły ogłosić znaczącą pozycję. Dla etykiet nienumerycznych stosuj aria-valuetext.