ARIA роли, състояния и свойства

Жива зона, която предава спешно, чувствително към времето съобщение. Екранните четци го обявяват незабавно, прекъсвайки текущото четене. Използвайте рядко — запазете за истински грешки и предупреждения; злоупотребата причинява умора от помощните технологии.

Диалог, който предава спешно съобщение и изисква отговор от потребителя. Съчетава семантиката на dialog с обявяването на alert. Използвайте само за деструктивни потвърждения, грешки, блокиращи по-нататъшната работа, или за прекъсвания, които не търпят отлагане.

Маркира самостоятелна композиция, която може да съществува независимо — публикация в блог, новина, отговор в форум или продуктова карта. Използвайте нативния елемент <article> на първо място; прибягвайте до role="article" само когато не можете да използвате HTML елемента.

Естествен HTML: <article>

Ориентирът за хедъра на целия сайт — обикновено съдържа логото, основната навигация и търсачката. Елементът <header> от най-горно ниво носи тази роля автоматично. На една страница може да има само един banner.

Естествен HTML: <header> (top-level)

Обозначава елемент като бутон — контрол, който задейства действие при активиране. Използвайте първо нативния HTML елемент <button>; прибягвайте до role="button" върху <div> или <span> само когато нативният елемент не може да се използва.

Естествен HTML: <button>

Маркира елемент като квадратче за отметка с две или три състояния. Препоръчва се използването на <input type="checkbox"> на първо място; към role="checkbox" се прибягва само когато не е възможно използването на нативния елемент — например за контрола с три състояния със смесена стойност.

Естествен HTML: <input type="checkbox">

Маркира текстово поле, свързано с изскачащ списък от стойности — за автодовършване, търсене с предсказване и падащи менюта. Нативният елемент <select> покрива простия случай с единичен избор; role="combobox" е необходим само когато се изисква филтриране, персонализирано рендиране или предложения от отдалечен API.

Естествен HTML: <select>

Ориентир за съдържание, което допълва основното съдържание, но е смислено само по себе си — странични колони, блокове със свързани статии, допълнителни информационни панели. Елементът <aside> носи тази роля, когато е на най-горното ниво.

Естествен HTML: <aside>

Ориентирът за долния колонтитул на сайта — авторски права, контакти, правни връзки. Елементът <footer> от най-горно ниво носи тази роля автоматично. Само един contentinfo на страница.

Естествен HTML: <footer> (top-level)

Маркира елемент като дефиниция на термин. Сдвоявайте с role="term" (или нативния <dfn>), за да свържете термина с неговата дефиниция. Използвайте нативните <dl>/<dt>/<dd> или <dfn> на първо място — те носят семантиката безплатно.

Естествен HTML: <dfn>

Маркира контейнер като модален или немодален диалог. Препоръчва се използването на нативния елемент <dialog> с showModal() — той осигурява захващане на фокуса, горния слой, фоновото покритие и затваряне с Escape без допълнителен код. Прибягвайте до role="dialog" само когато нативният елемент е невъзможен.

Естествен HTML: <dialog>

Обозначава самостоятелен илюстративен блок — изображение, диаграма, листинг на код — обикновено придружен от надпис. Използвайте първо нативния елемент <figure>; прибягвайте до role="figure" само когато хост елементът не може да бъде <figure>.

Естествен HTML: <figure>

Ориентир за формуляр — колекция от контроли за въвеждане на данни, които изпращат информация. Елементът <form> се обявява като ориентир за формуляр САМО когато има достъпно наименование. Без наименование той е просто формуляр, а не ориентир.

Естествен HTML: <form aria-label>

Отбелязва обща група от свързани елементи. Семантично по-леко от ориентир — екранните четци не обявяват групите в менюто с ориентири. За групирани контроли в форма използвайте <fieldset> + <legend>; прибягвайте до role="group" за нефункционални групирания.

Естествен HTML: <fieldset>

Маркира елемент като заглавие. Първо се използват <h1>–<h6> — те носят правилната семантика и правилното ниво безплатно. Към role="heading" се прибягва само когато трябва да се повиши елемент, който не може да бъде <h*>.

Естествен HTML: <h1> – <h6>

Маркира елемент като хипервръзка — контрола, която при активиране навигира към нов ресурс. На първо място трябва да се използва нативният HTML елемент <a href>; прибягвайте до role="link" на <span> или <div> само когато нативният елемент е невъзможен.

Естествен HTML: <a href>

Отбелязва елемент като списък от елементи. Използвайте първо <ul>, <ol> или <dl> — нативният елемент носи ролята, броя и визуалния маркер. Прибягвайте до role="list" само когато CSS list-style: none задейства евристиката на Safari за премахване на ролята на списъка.

Естествен HTML: <ul> / <ol>

Отбелязва елемент като списък от избираеми опции. Използвайте <select> за простия случай с единичен избор — той осигурява удобен за мобилни устройства selector и пълна поддръжка на клавиатура. Прибягвайте до role="listbox", когато се нуждаете от персонализиран стил, множествен избор или съчетаване с комбинирано поле.

Естествен HTML: <select> (single-select)

Обозначава елемент като един елемент от списък. Използвайте <li> вътре в <ul> или <ol> — нативният елемент носи ролята и позицията в множеството. Прибягвайте до role="listitem" само когато е сдвоен с изричен role="list" върху родителски елемент, различен от списък.

Естествен HTML: <li>

Ориентирът за основното съдържание на страницата — основното съдържание, без повтарящи се заглавки, навигация и долни колонтитули. Елементът <main> носи тази роля автоматично. Точно един main на страница.

Естествен HTML: <main>

Маркира контейнер като приложно меню — изскачащото меню от тип „Файл/Редактиране“ или контекстно меню. Няма HTML еквивалент. Навигационен списък на сайт НЕ е меню; използвайте <nav> с <ul> от връзки.

Маркира контейнер като постоянна лента с менюта — винаги видимата хоризонтална лента от менюта от вида File/Edit/View, характерна за десктоп приложения. Различна е от menu, което е изскачащо меню. На уеб почти никога не е правилният шаблон.

Маркира елемент като действащ запис вътре в меню или лента с менюта. Няма HTML еквивалент — менютата са конструкция само за ARIA. Тази роля се използва единствено при изграждане на истинско меню от тип приложение; обикновен навигационен списък НЕ трябва да използва menu/menuitem.

Ориентир, групиращ набор от навигационни връзки — основна навигация, навигационна пътека, съдържание на страницата. Елементът <nav> носи тази роля автоматично. Множество навигационни елементи на страница са обичайни и допустими, но всеки трябва да има уникално достъпно наименование.

Естествен HTML: <nav>

Маркира елемент като избираем елемент в списъчно поле. Опцията ТРЯБВА да е наследник на listbox (пряко или чрез aria-owns). Използвайте нативния <option> в <select>; прибягвайте до role="option" само при изграждане на потребителско listbox или изскачащо меню на combobox.

Естествен HTML: <option>

Отбелязва елемент като индикатор за напредък. Използвайте първо <progress> — той осигурява семантиката, детерминирания визуален изглед и атрибутите за стойност нативно. Прибягвайте до role="progressbar", когато задължително трябва да стилизирате отвъд възможностите на нативния елемент.

Естествен HTML: <progress>

Обозначава елемент като единична опция в група с взаимно изключващ се избор. Радио бутонът трябва да е вътре в radiogroup (или нативен fieldset). Използвайте <input type="radio"> първо; прибягвайте до role="radio" само когато нативният input е невъзможен.

Естествен HTML: <input type="radio">

Общ ориентир за съдържание, което не отговаря на banner, main, navigation, complementary или contentinfo, но е достатъчно важно, за да се навигира до него. Елементът <section> се превръща в ориентир region само когато има достъпно наименование.

Естествен HTML: <section aria-label>

Ориентир, групиращ форма за търсене. Позволява на потребителите на екранни четци да преминат директно към търсенето в сайта. Нативният елемент <search> (HTML 2024) носи тази роля автоматично; за по-широка поддръжка от браузърите днес се използва role="search" върху <form>.

Естествен HTML: <search>

Маркира елемент като текстово поле за въвеждане, ограничено до задача за търсене. Препоръчва се използването на <input type="search"> — осигурява бутон за изчистване и семантика за търсене. Прибягва се до role="searchbox" само при персонализирано поле за търсене, базирано на contenteditable.

Естествен HTML: <input type="search">

Маркира елемент като разделител между секции на съдържание или елементи в съставен уиджет. Използвайте първо <hr> за тематични прекъсвания в текст; прибягвайте до role="separator" при разделяне на елементи в меню, лента с инструменти или друг уиджет.

Естествен HTML: <hr>

Маркира елемент като вход, избиращ стойност от диапазон. Използвайте първо <input type="range">; прибягвайте до role="slider" само когато се нуждаете от потребителска следа — например двуплъзгач за избор на диапазон, който родното решение не поддържа.

Естествен HTML: <input type="range">

Активна зона, която предава неспешна информация с препоръчителен характер. Екранните четци обявяват промените с учтивост — при следващата пауза в речта, без да прекъсват. Използвайте за рутинни потвърждения, броячи и актуализации за напредък. Нативният елемент <output> носи тази роля.

Естествен HTML: <output>

Отбелязва елемент като превключвател вкл./изкл. По функционалност е близо до checkbox, но се обявява като "switch, on" или "switch, off", а не "checked" — по-точно описва превключвател в настройки. Все още няма нативен HTML еквивалент.

Обозначава елемент като един таб в интерфейс с табове. Табът ТРЯБВА да е вътре в tablist и ТРЯБВА да реферира асоциирания tabpanel чрез aria-controls. Няма нативен HTML елемент за таб — таб шаблонът е изцяло базиран на ARIA.

Маркира контейнер като лента с раздели в интерфейс с раздели. Съдържа дъщерни елементи с role="tab". Разделите и панелите с раздели са шаблон само за ARIA — в HTML няма нативен tablist.

Маркира панела със съдържание, свързан с таб. Всеки tabpanel е наименован от своя таб чрез aria-labelledby; табът препраща към панела чрез aria-controls. Показвайте по един панел наведнъж; скривайте останалите с атрибута hidden.

Маркира елемент като едноредово или многоредово поле за въвеждане на текст. Използвайте първо <input type="text"> или <textarea> — те осигуряват цялото поведение на textbox безплатно. Прибягвайте до role="textbox" само при изграждане на редактор за богат текст върху contenteditable елемент.

Естествен HTML: <input type="text"> / <textarea>

Маркира контейнер като лента с инструменти — групиран набор от свързани контроли (лента за форматиране, ред с иконни бутони). Намалява броя на точките за достъп с Tab: лента с 10 бутона се превръща в една точка на достъп, а между бутоните се навигира с клавишите-стрелки.

Маркира елемент като йерархичен контейнер от treeitem-и — файлов браузър, вложени категории или организационна схема. Единична Tab-спирка, навигация с клавиши-стрелки, разгъване/свиване. Няма нативен HTML еквивалент.

Маркира елемент като един възел вътре в дърво. Treeitem може да бъде разгъваем (родител на повече treeitems) или краен (лист). Използвайте само при изграждане на йерархичен навигатор — файлов експлорер, организационна схема, вложени категории — с навигация чрез стрелки с единична спирка с таб.

Управлява дали помощната технология обявява цялото съдържание на живия регион при актуализация или само частта, която се е променила. По подразбиране е "false" (само разликата). Задайте "true", когато контекстът има смисъл единствено като цяло изречение.

Отбелязва дадена област като намираща се в процес на обновяване, така че помощните технологии да потиснат междинните съобщения. Задава се на "true" при зареждане или при мащабни промени в DOM; превключва се на "false", когато областта е стабилна.

Указва текущото отметнато състояние на квадратче за отметка, радио бутон или елемент от менюто с подобна семантика. Приема стойности "true", "false" или "mixed". Нативното HTML квадратче за отметка управлява това автоматично — задавайте атрибута ръчно само при персонализирани уиджети.

Маркира елемента, представляващ текущия елемент в набор — активната страница в навигацията, текущата стъпка в съветник, днешната дата в календар. По-конкретно от aria-selected; използвайте го върху връзки и елементи, за които „избиране“ не е подходящата метафора.

Указва, че даден контрол е видим и може да получи фокус, но не реагира на потребителски вход. Предпочитайте нативния HTML атрибут disabled, когато е наличен; прибягвайте до aria-disabled, когато елементът трябва да остане фокусируем или да може да показва подсказка.

Указва дали сгъваем елемент — бутон за разкриване, комбинирано поле, меню, елемент от дърво — е отворен в момента. Приема "true" или "false". Обикновено се съчетава с aria-controls, сочещ към областта, която контролът отваря.

Премахва елемент и всички негови потомци от дървото за достъпност. Потребителите с добро зрение все още виждат елемента; помощните технологии никога не достигат до него. Запазен за декоративно съдържание — никога не се прилага към фокусируем елемент за управление.

Указва, че контрол на формуляр е неуспешен при валидация. Свържете с aria-describedby, сочещ към четимото от човека съобщение за грешка, така че екранният четец да обяви едновременно невалидното състояние и причината.

Маркира регион, чиито актуализации трябва да бъдат обявявани от помощните технологии, без да се премества фокусът. За повечето случаи се избира "polite", а "assertive" — само за наистина спешни актуализации. Регионът трябва да присъства в DOM при първоначалното визуализиране.

Казва на помощните технологии да третират останалата част от страницата като неактивна докато диалогът е отворен. Задайте на "true" върху role="dialog" или role="alertdialog". Не прави фона наистина неактивен — свържете с атрибута inert или капан за фокус.

Указва дали бутон-превключвател е в момента натиснат. Задайте "true", когато превключвателят е включен, и "false", когато е изключен; помощната технология обявява състоянието заедно с етикета.

Указва, че стойността на контрол за формуляр не може да се редактира, но контролът остава оперативен — достъпен за фокус, за копиране и се изпраща заедно с формуляра. Различава се от aria-disabled, който прави контрола неоперативен.

Указва, че елемент вътре в контейнер с единичен или множествен избор е текущо избран. Използва се при роли tab, option, gridcell, treeitem и подобни. Отличен от aria-checked (checkbox/radio) и aria-pressed (бутон с превключване).

При композитен уиджет сочи към ID на потомъка, който е текущо активен. DOM фокусът остава върху контейнера, докато виртуален фокус се движи между дъщерните елементи. Алтернатива на roving tabindex за listbox-ове, combobox-ове и grid-ове.

При текстово поле или комбинирана кутия декларира какъв вид автодовършване предлага контролата — вградени предложения, списък с опции, и двете, или нито едно. Не трябва да се бърка с HTML атрибута autocomplete, който се отнася до семантиката на полета за формуляри в браузъра.

Назовава елемента или елементите, чието присъствие или съдържание този контрол управлява. Типични двойки: таб контролира tabpanel, бутон за разкриване контролира разкрит регион. Поддръжката при помощните технологии е неравномерна — използвайте рядко.

Препраща към един или повече идентификатори на елементи, чийто текст се превръща в разширеното описание на този елемент. Обявява се след достъпното наименование. Използва се за помощен текст, подсказки за формат и вградени съобщения за грешки.

Информира помощните технологии, че активирането на даден контрол ще отвори изскачащ елемент, и указва какъв е неговият тип. Приема стойностите "menu", "listbox", "tree", "grid", "dialog" или "true" / "false". Комбинирайте с aria-expanded, за да може помощната технология да обяви и дали изскачащият елемент е отворен.

Предоставя достъпно наименование като низ, когато няма видим текст. Използвайте само когато липсва екранен надпис — ако видим текст съществува, предпочете aria-labelledby, за да съвпадат произнесеното наименование и видяното от потребителя.

Препраща към един или повече идентификатори на елементи, чийто видим текст се превръща в достъпното наименование на този елемент. Предпочитано пред aria-label, когато текст на екрана вече описва контролата.

Указва йерархичното ниво на елемент в структура. Задължителен за елементи с role="heading"; използва се също за role="treeitem" и role="listitem" в рамките на вложени списъци. Целочислена стойност, започваща от 1.

Декларира връзка родител-дете в дървото за достъпност, когато DOM структурата не я изразява. Прехвърля референтните елементи като деца на текущия елемент за целите на помощните технологии. Мощен инструмент — лесен за злоупотреба.

Позиция на елемент в набор, когато DOM не може да я изрази — обикновено защото елементите са виртуализирани, разпределени по страници или филтрирани. Винаги трябва да се комбинира с aria-setsize, така че екранните четци да могат да обявят „3 от 47“.

Указва, че потребителско въвеждане е задължително за даден контрол преди изпращане на формуляр. Използвайте HTML атрибута required за нативни полета; прибягвайте до aria-required само когато HTML еквивалент не съществува — напр. combobox, изграден върху div.

Общ брой елементи в набор, когато DOM не ги съдържа всички. Сдвоява се с aria-posinset, за да може екранният четец да обяви „елемент 14 от 5000“ дори ако са изобразени само пет. Използвайте -1, ако общият брой е неизвестен.

Върху заглавна клетка на колона или ред в сортируема таблица или решетка, обявява текущата посока на сортиране. Стойности: "ascending", "descending", "other" или "none". В даден момент само едно заглавие в таблицата трябва да носи сортирана стойност.

Текущата числова стойност на уиджет от тип „диапазон“ — плъзгач, лента за напредък, поле за въртяща се стойност, лента за превъртане. Комбинирайте с aria-valuemin и aria-valuemax, за да може помощната технология да обяви смислена позиция. Използвайте aria-valuetext за нечислови надписи.