What Is an ARIA Role Reference?

An ARIA role reference is a searchable catalog of WAI-ARIA roles, organized by category with descriptions, required properties, allowed children, usage guidance, and code examples. It serves as a quick-reference tool for developers building accessible web interfaces.

WAI-ARIA defines over 80 roles across six categories — document structure, landmark, widget, window, live region, and abstract. This tool lets you browse, search, and filter roles by category, see which properties and states apply to each role, and copy implementation examples directly into your code.

How to Use This Tool

1. Browse by category — Filter roles by their WAI-ARIA category — landmark roles (banner, navigation, main), widget roles (button, checkbox, slider), document structure roles (article, heading, list), and live region roles (alert, log, status).
2. Search for specific roles — Type a role name or keyword to find the exact role you need. The search matches role names, descriptions, and related properties for comprehensive results.
3. Review role details — Each role entry shows its category, description, required and supported ARIA properties, allowed parent and child roles, implicit HTML equivalents, and practical usage guidance.
4. Copy code examples — Each role includes ready-to-use HTML code examples showing proper implementation with the necessary ARIA attributes. Copy and adapt them for your project.

Tips and Best Practices

• → Prefer native HTML elements. The first rule of ARIA is: if a native HTML element does the job, use it instead of ARIA. A native button is always better than a div with role='button' because it comes with built-in keyboard handling, focus management, and screen reader support.
• → Don't change native semantics. Avoid adding roles that conflict with an element's native semantics. Adding role='heading' to a button creates confusion for assistive technologies. Use the right element for the job instead.
• → Always support keyboard interaction. Adding an ARIA role doesn't add behavior. If you use role='button' on a div, you also need to handle Enter and Space key presses, manage focus, and implement the expected interaction pattern.
• → Test with actual screen readers. ARIA roles are consumed by assistive technologies. Test your implementation with VoiceOver, NVDA, or JAWS to verify that roles, states, and properties produce the expected announcements and navigation behavior.

Frequently Asked Questions

Built by Derek Giordano · Part of Ultimate Design Tools

Privacy Policy · Terms of Service