ARIA Role Reference
Comprehensive searchable database of ARIA roles with descriptions, usage guidelines, and code examples.
Description: A message with important, time-sensitive information
Usage: Use for dynamic content that needs immediate attention
Example:
Description: A region with application-like behavior
Usage: Use sparingly for web applications that handle keyboard events
Example:
Description: A section of content that forms an independent part
Usage: Use for blog posts, articles, forum posts
Example:
Description: Site-wide content, typically a header
Usage: Use for page header/logo area
Example:
Description: An input that allows user-triggered actions
Usage: Use when creating custom buttons from div/span elements
Example:
Description: A checkable input with three states: true, false, or mixed
Usage: Use for custom checkbox implementations
Example:
Description: A composite widget with a textbox and popup
Usage: Use for autocomplete and searchable dropdowns
Example:
Description: Supporting content related to main content
Usage: Use for sidebars and related content
Example:
Description: Information about the page, typically a footer
Usage: Use for page footer with copyright/contact info
Example:
Description: The definition of a term
Usage: Use with term role for definitions
Example:
Description: A dialog or window that prompts the user for information
Usage: Use for modal dialogs and overlays
Example:
Description: A region containing document content
Usage: Use for embedded documents
Example:
Description: A scrollable list of articles
Usage: Use for social media feeds or news streams
Example:
Description: A container for graphic content with caption
Usage: Use for images with captions
Example:
Description: A landmark region containing form elements
Usage: Use for search forms or important forms
Example:
Description: An interactive data table or grid
Usage: Use for editable data grids
Example:
Description: A cell in a grid or treegrid
Usage: Use for individual cells in data grids
Example:
Description: A set of user interface objects
Usage: Use to group related elements
Example:
Description: A container for image elements
Usage: Use for complex images made of multiple elements
Example:
Description: A section containing list items
Usage: Use when semantic list markup isn't possible
Example:
Description: A list from which users can select items
Usage: Use for custom select dropdowns
Example:
Description: A single item in a list
Usage: Use for items in non-semantic lists
Example:
Description: A region for sequentially updated information
Usage: Use for chat logs or status logs
Example:
Description: The main content of the document
Usage: Use once per page for primary content
Example:
Description: Content that scrolls automatically
Usage: Use for auto-scrolling announcements
Example:
Description: Mathematical expression
Usage: Use for mathematical content
Example:
Description: A list of choices or actions
Usage: Use for dropdown menus
Example:
Description: A presentation of menu choices in a horizontal bar
Usage: Use for horizontal menu bars
Example:
Description: An option in a menu
Usage: Use for individual menu options
Example:
Description: A collection of navigational elements
Usage: Use for major navigation blocks
Example:
Description: Synonym for presentation role
Usage: Use to remove semantic meaning
Example:
Description: A section with parenthetic or ancillary content
Usage: Use for footnotes or side notes
Example:
Description: A selectable item in a listbox
Usage: Use for items in listbox widgets
Example:
Description: An element whose semantics should be ignored
Usage: Use to remove semantic meaning from layout elements
Example:
Description: An element displaying progress of a task
Usage: Use for progress indicators
Example:
Description: A checkable input in a group of radio roles
Usage: Use for custom radio button implementations
Example:
Description: A group of radio buttons
Usage: Use to group related radio buttons
Example:
Description: A landmark region with specific purpose
Usage: Use for important page sections with aria-label
Example:
Description: A row of cells in a grid
Usage: Use for rows in grids and tables
Example:
Description: A landmark region for search functionality
Usage: Use for search input areas
Example:
Description: An input for selecting a value from a range
Usage: Use for custom slider controls
Example:
Description: An input for selecting from discrete choices
Usage: Use for number spinners
Example:
Description: A container for status updates
Usage: Use for status messages and notifications
Example:
Description: A checkbox representing on/off values
Usage: Use for toggle switches
Example:
Description: A clickable element inside a tablist
Usage: Use for individual tabs in a tab interface
Example:
Description: A container for a set of tab elements
Usage: Use for tab interface containers
Example:
Description: Content associated with a tab
Usage: Use for content panels in tab interfaces
Example:
Description: A word or phrase being defined
Usage: Use for glossary terms
Example:
Description: An input for free-form text
Usage: Use for custom text input implementations
Example:
Description: A numerical counter showing elapsed time
Usage: Use for countdown timers
Example:
Description: A collection of commonly used controls
Usage: Use for toolbars with action buttons
Example:
Description: Contextual popup displaying information
Usage: Use for custom tooltips
Example:
Description: A hierarchical list structure
Usage: Use for file trees or nested navigation
Example:
Description: An item in a tree widget
Usage: Use for items in tree structures
Example:
What are ARIA Roles?
ARIA (Accessible Rich Internet Applications) roles are attributes that define the purpose and behavior of elements to assistive technologies like screen readers. They help make dynamic web applications accessible to users with disabilities.
How to Use This Reference:
- Search: Enter keywords to find specific ARIA roles (e.g., "button", "navigation", "menu")
- Browse: Scroll through all available roles to discover options
- Learn: Read the description and usage guidelines for each role
- Copy Example: Use the code examples as templates for your projects
- Test: Implement the role and test with screen readers
ARIA Role Categories:
Landmark Roles
Define page structure: banner, navigation, main, contentinfo, complementary, search, form, region
Widget Roles
Interactive elements: button, checkbox, radio, textbox, slider, switch, spinbutton
Composite Roles
Complex widgets: tablist, tab, tabpanel, menu, menubar, menuitem, listbox, combobox, grid
Document Structure Roles
Content organization: article, list, listitem, row, group, figure, img
Live Region Roles
Dynamic content: alert, status, log, timer, marquee
Best Practices:
- Use Native HTML First: Prefer
<button>over<div role="button">when possible - Add Keyboard Support: Elements with interactive roles need keyboard event handlers
- Include aria-label: Many roles need labels for context (e.g.,
aria-label="Main navigation") - Test with Screen Readers: Always test ARIA implementations with actual assistive technologies
- Don't Override Semantics: Avoid putting ARIA roles on elements that already have appropriate semantics
- Validate Your Code: Use accessibility validators to check ARIA usage
Common ARIA Attributes:
<button aria-label="Close dialog">×</button>
<div role="dialog" aria-labelledby="dialogTitle">
<input aria-describedby="passwordHelp">
<div aria-hidden="true">Decorative content</div>
<button aria-expanded="false" aria-controls="menu">Menu</button>
<div role="checkbox" aria-checked="true">
<li role="option" aria-selected="true">Option 1</li>
<div aria-live="polite">Status updates...</div>
Examples of Common Patterns:
<div role="dialog" aria-labelledby="dialogTitle" aria-modal="true">
<h2 id="dialogTitle">Confirm Action</h2>
<p>Are you sure?</p>
<button>Confirm</button>
<button>Cancel</button>
</div><div role="tablist" aria-label="Content tabs">
<button role="tab" aria-selected="true" aria-controls="panel1">Tab 1</button>
<button role="tab" aria-selected="false" aria-controls="panel2">Tab 2</button>
</div>
<div role="tabpanel" id="panel1">Content 1</div>
<div role="tabpanel" id="panel2" hidden>Content 2</div><button aria-haspopup="true" aria-expanded="false" aria-controls="menu1">
Menu
</button>
<ul role="menu" id="menu1" hidden>
<li role="menuitem">Option 1</li>
<li role="menuitem">Option 2</li>
<li role="menuitem">Option 3</li>
</ul>Testing Your ARIA Implementation:
- Screen Readers: Test with NVDA (Windows), JAWS (Windows), or VoiceOver (Mac/iOS)
- Browser DevTools: Use accessibility inspectors in Chrome, Firefox, or Edge
- Automated Tools: Run axe, WAVE, or Lighthouse accessibility audits
- Keyboard Navigation: Ensure all interactive elements are keyboard accessible
Related Tools:
- Screen Reader Preview - See how screen readers interpret your HTML
- Focus Order Analyzer - Check keyboard navigation and tab order
- WCAG Contrast Checker - Verify color contrast ratios
- Alt Text Analyzer - Check image accessibility
- HTML Validator - Validate HTML markup