Learn how to enhance web accessibility using ARIA roles. This in-depth guide covers ARIA roles for accessible web development, including best practices and practical examples to make your site more inclusive.
A screen reader doesn’t see your interface. It hears the meaning behind it. So a div you styled to look like a button is, to that user, silence.
That gap is what Accessible Rich Internet Applications (ARIA) exists to close. It’s a W3C specification that tells assistive technologies what a piece of your UI is and how it behaves, for the times plain HTML can’t say so on its own.
This is Part 1: the map. We’ll walk the ARIA roles category by category so you know the whole vocabulary before writing a line of it. One warning up front, and we’ll come back to it: the best ARIA is usually no ARIA. Reach for a native HTML element first, and add a role only when HTML runs out of words.
Understanding ARIA Roles
A role answers one question for the screen reader: what is this thing? A tab, a dialog, an alert, a list. Set it, and the assistive technology knows how to announce the element and what behavior to expect.
The spec sorts roles into a handful of categories, and learning them in groups beats memorizing a flat list. Here’s the map.
Abstract Roles
Start here so you can skip it. Abstract roles are the scaffolding the spec uses to organize every other role. You never put them in your markup: the specification says authors must not use abstract roles in content. They’re listed so the taxonomy makes sense, nothing more.
command
composite
input
landmark
range
roletype
section
sectionhead
select
structure
widget
windowComposite Roles
Composite roles are containers that manage other widgets. They wrap several interactive parts into one component the user drives with the keyboard. A combobox pairs a text input with a popup list, so typing filters the choices. Grids, menus, and tab lists follow the same pattern: one role outside, coordinating the pieces inside.
combobox
grid
listbox
menu
menubar
radiogroup
tablist
tree
treegridWidget Roles
Widget roles are the individual controls, the parts a person clicks, checks, or drags. Some stand alone, others live inside a composite. Buttons, checkboxes, sliders, switches, tabs. If it does something when you interact with it, it’s probably a widget role.
button
checkbox
gridcell
link
menuitem
menuitemcheckbox
menuitemradio
option
progressbar
radio
scrollbar
searchbox
separator
slider
spinbutton
switch
tab
tabpanel
textbox
treeitemDocument Structure Roles
Structure roles describe content rather than controls: lists, tables, figures, headings. They tell assistive tech how the page is organized so a reader can move through it in order. Most map straight to HTML you already know, which is why you’ll rarely type them by hand.
One flag before the list: directory was deprecated in WAI-ARIA 1.2. It never did anything a plain list didn’t, so use the list role, or better, a native <ul> or <ol>.
application
article
cell
columnheader
definition
directory
document
feed
figure
group
heading
img
list
listitem
math
none
note
presentation
row
rowgroup
rowheader
separator
table
term
toolbar
tooltipLandmark Roles
Landmarks are signposts. They mark the big regions of a page, the header, nav, main content, search, so a screen reader user can jump straight to what they want instead of wading through everything above it. This is the ARIA that pays off fastest, and most of it comes free from HTML elements like <nav> and <main>.
banner
complementary
contentinfo
form
main
navigation
region
searchLive Region Roles
Live regions handle the parts of a page that change after it loads: a form error, a “saved” confirmation, a cart total ticking up. Mark the region and the screen reader announces the update on its own. An alert interrupts whatever’s being read; a status waits its turn.
alert
log
marquee
status
timerWindow Roles
Window roles cover things layered over the page, like dialogs and modals. There are only two, and the difference is urgency. A dialog is your standard modal; an alertdialog carries an urgent message and expects a response, like a “discard your changes?” prompt.
alertdialog
dialogBest Practices for Using ARIA Roles
A few habits keep you out of trouble, and the first is the one people skip most:
- Reach for native HTML first: This is the first rule of ARIA. If an element already has the role and behavior you need built in, use it. A real
buttonbeats adivwithrole="button", and you get keyboard and focus handling for free. - Don’t add roles you don’t need:
role="navigation"on a<nav>is just noise. The element already says it. - Test with a real screen reader: Markup that looks right can still sound wrong. Run it through VoiceOver or NVDA and listen.
- Revisit it as the UI changes: Roles drift out of sync when components get refactored. When the markup moves, check the roles still match.
Conclusion
That’s the vocabulary: seven categories, from the abstract roles you’ll never touch to the landmarks and live regions you’ll reach for often. Learn the map and the individual roles stop feeling like jargon.
But the names aren’t the point. The point is a web that works for the person using a screen reader to read your post, buy from your store, or fill out your form. That’s the open web doing its job.
In Part 2, we’ll put these roles into real markup: where they help, where they get in the way, and how to tell the difference.