Warning
This page is a work in progress and will be updated in the future.
Info
This post contains AI generated content and will be marked explicitly.
Role attributes
Here’s a reference table for common roles. Sorted by a guess of how common they are.
| Role Name | Description | Usage Notes (ai generated) |
|---|---|---|
role="img" | Indicates an element is an image. | Generally used when an <img> tag isn’t feasible, such as background images with semantic meaning. Ensure an aria-label or aria-labelledby provides equivalent alternative text. |
role="button" | Identifies an element as a clickable button. | Often used when creating custom button-like controls from non-button elements (e.g., <div>). Requires keyboard event handling (Space/Enter) and focus management. |
role="navigation" | Identifies a collection of navigational links. | Use for primary navigation menus or significant sets of links. Aids screen reader users in quickly finding navigation sections. |
role="link" | Designates an interactive element as a hyperlink. | Primarily used when an <a> tag with an href isn’t suitable, but the element functions as a link (e.g., a custom routing solution). Requires keyboard event handling and focus. |
role="dialog" | Designates an overlay window that requires user interaction before proceeding. | Used for modal dialogs (pop-ups). Requires careful focus management (trap focus within the dialog), keyboard handling (Esc to close), and aria-modal="true". |
role="alert" | Communicates an important, time-sensitive message to the user. | For dynamic content updates that require immediate attention but aren’t interruptive (e.g., “Item added to cart”). Use aria-live="assertive" for critical, high-priority messages. |
role="search" | Identifies a section of the page containing search functionality. | Helpful for screen reader users to quickly locate search forms. |
role="list" | Groups a collection of static, related items. | Similar to <ul> or <ol>. Items within a list typically use role="listitem". list is for presentational or informational lists. Users can generally navigate the entire list. Example: a list of blog posts. |
role="listbox" | Identifies a widget that presents a list of options from which the user can select one or more. | listbox is for interactive selection widgets. Items within a listbox use role="option". It supports single (aria-multiselectable="false") or multiple selection (aria-multiselectable="true"). Users typically navigate options using arrow keys and select with Space/Enter. Example: a dropdown select menu. This is a common pattern for custom select elements. |
role="toolbar" | A collection of commonly used functions or controls presented in a compact visual area. | Think of an editor’s toolbar (bold, italic, underline). Contains interactive elements like buttons. |
role="grid" | Identifies a composite widget that contains a collection of items, each with several editable properties, organized in rows and columns. | For tabular data that is interactive or editable, beyond just presentation (<table>). Requires nested role="row" and role="gridcell". Complex, use only when native <table> or CSS Grid isn’t sufficient for the desired interactive behavior. |
role="tablist" | A container for a set of tab elements. | Used for tabbed interfaces. Requires nested role="tab" for each tab and role="tabpanel" for the associated content. Keyboard navigation (arrow keys to switch tabs) and focus management are crucial. |
role="status" | A live region where new content is added and old content may be removed. | For non-critical updates that are important but don’t require immediate user action (e.g., “Loading complete”). Similar to aria-live="polite". |
role="form" | Identifies a region that contains an interactive form. | Primarily for grouping related form controls. Can be useful if a form is not wrapped in a <form> element. Screen readers can often jump to forms. |
role="application" | Indicates that the element and its children represent a web application, rather than a traditional web document. | Use with extreme caution. This role tells assistive technologies to pass all keyboard events directly to the application, bypassing the browser’s default handling. Only use if you are completely re-implementing standard browser behaviors (e.g., focus management, keyboard shortcuts) for all descendant elements. Most common web pages are documents, not applications in this sense. Misuse can severely degrade accessibility. |