Właściwość Relacja

`aria-label`

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.

Kiedy używać

Gdy element sterujący nie ma widocznego tekstu — przyciski z samą ikoną, pola wyszukiwania z jedynie lupą, przyciski zamknięcia (×), ikony mediów społecznościowych. Ciąg znaków wpisany w aria-label staje się dostępną nazwą elementu, którą czytniki ekranu ogłaszają zamiast ewentualnego tekstu wewnętrznego.

Natywnym odpowiednikiem w HTML jest element <label> dla pól formularza lub widoczny tekst przycisku. Po aria-label sięgaj tylko wtedy, gdy żadne z tych rozwiązań nie jest możliwe.

Działanie

Przyjmuje pojedynczy ciąg znaków. Cokolwiek wpiszesz w aria-label, nadpisuje wszelki widoczny tekst wewnątrz elementu — dostępna nazwa jest tym, co słyszą użytkownicy AT, ale jest niewidoczna dla użytkowników widzących. Ta asymetria jest źródłem większości błędów z tym atrybutem.

Ciąg znaków nie jest automatycznie tłumaczony. Jeśli Twoja witryna obsługuje wiele języków, wartość aria-label musi być lokalizowana jak każdy inny ciąg interfejsu użytkownika. Czytniki ekranu traktują wartość jako zwykły tekst — bez HTML, bez podziałów wiersza, bez znaczników.

Jeśli element ma widoczny tekst, preferuj aria-labelledby wskazujące na ten tekst, by widoczna etykieta i dostępna nazwa pozostawały zsynchronizowane.

Typowe błędy

Wpisanie aria-label="Kliknij tutaj" na przycisku, który już mówi „Złóż zamówienie” — widoczny tekst jest teraz ukryty przed AT, a użytkownik słyszy złą informację.
Naruszenie WCAG 2.5.3 Label in Name: aria-label="Wyślij" na przycisku, którego widoczny tekst mówi „Złóż zamówienie”, oznacza, że użytkownik sterowania głosem nie może powiedzieć „kliknij Złóż zamówienie”, by go aktywować.
Dodawanie aria-label do elementu nieinteraktywnego jak <div> lub <span> — większość przeglądarek ignoruje to, bo element nie ma roli obsługującej nazwę.
Pozostawianie wartości nieprzetłumaczonej, gdy reszta strony jest w innym języku.
Używanie aria-label zamiast prawdziwego <label> na polu formularza, co niszczy możliwość fokusowania pola przez kliknięcie etykiety.
Wpychanie instrukcji do aria-label zamiast aria-describedby. Nazwa powinna być krótka; tekst pomocniczy trafia do opisu.

Przykład

<!-- Przycisk z samą ikoną: brak widocznego tekstu, aria-label jest wymagane -->
<button type="button" aria-label="Zamknij dialog">
  <svg aria-hidden="true" focusable="false">…</svg>
</button>

<!-- Widoczny tekst + ikona: NIE używaj tu aria-label -->
<button type="button">
  <svg aria-hidden="true" focusable="false">…</svg>
  Zamknij dialog
</button>