HTML ARIA role attribute - a convenient Testing Library query table

Mar 2, 2023

It's March 2023 and there is a good trend going around with using testing-library and its ...ByRole query. I quite like querying elements this way, but to be honest with you sometimes it's not all that clear wether which role do you have in your components if any. So I thought I would write a small post about it and include a cheat-sheet for the most common roles.

HTML ARIA role attribute explained

ARIA roles provide semantic meaning to content, allowing screen readers and other tools to present and support interaction with object in a way that is consistent with user expectations of that type of object. ARIA roles can be used to describe elements that don't natively exist in HTML or exist but don't yet have full browser support.


HTML Elements default roles are listed in the table below.

Please not that examples that have role attribute defined DO require those attributes. For example, <fieldset role="radiogroup"></fieldset> will not work without role="radiogroup", even though it's more semantically correct than say <div role="radiogroup"></div>.

headingDefines this element as a heading to a page or sectionh1..h6Document Structure<h1></h1>
buttonA clickable elementbuttonWidget<button></button>
linkLink only with href attribute, otherwise genericaWidget<a href="URL"></a>
imgAn imageimgDocument Structure<img src="URL" alt="placeholder image">
listA list of itemsul,ol,menuDocument Structure<ul></ul>
listitemAn item in a listliDocument Structure<li></li>
separatorA divider that separates and distinguishes sections of content or groupshrDocument Structure<hr>
mainMain content of the pagemainLandmark<main></main>
navigationCollection of navigational elements (usually links) for navigating the document or related documentsnavLandmark<nav></nav>
complementarySupporting section of the document, designed to be complementary to the main content at a similar level in the DOM hierarchy, but remains meaningful when separated from the main contentasideLandmark<aside></aside>
contentinfoFooter for its nearest sectioning content or sectioning root elementfooterLandmark<footer></footer>
formRegion that contains a collection of items and objects that, as a whole, combine to create a formformLandmark<form></form>
regionSection of the page that contains content that is important enough to be included in a page summary or table of contentssectionLandmark<section></section>
searchRegion that contains a collection of items and objects that, as a whole, combine to create a search facilityformLandmark<form role="search"></form>
textboxA single-line text boxinputWidget<input type="text">
checkboxA checkable input that has three possible values: true, false, or mixedinputWidget<input type="checkbox">
radioA checkable input that has two possible values: true or falseinputWidget<input type="radio">
searchboxA single-line text box for entering search queriesinputWidget<input type="search">
tableA table containertableDocument Structure<table></table>
rowheaderA cell containing header information for a rowthDocument Structure<th scope="row"></th>
columnheaderA cell containing header information for a columnthDocument Structure<th scope="col"></th>
rowgroupA group of rows that consists of a row header and data rows for that row headerthead,tbody,tfootDocument Structure<tbody></tbody>
rowA row in a table containertrDocument Structure<tr></tr>
cellA cell in a table container. (if the ancestor table element is exposed as a role=table)td,thDocument Structure<td></td>
groupA group of user interface objects which are not intended to be included in a page summary or table of contents by assistive technologiesfieldsetWidget<fieldset></fieldset>
radiogroupA group of radio buttonsWidget<fieldset role="radiogroup"></fieldset>
articleA section of a page that consists of a composition that forms an independent part of a document, page, or sitearticleDocument Structure<article></article>
termA definition of a termdfn,dtDocument Structure<dfn></dfn>
definitionA definition of a termDocument Structure<dfn role="definition"></dfn>
figureA section that contains content that is referenced from the main flow of the document, but that could be moved away from the main content without losing meaningfigureDocument Structure<figure></figure>
optionAn option in a select listoptionWidget<option></option>
progressbarAn element that displays the progress status for tasks that take a long timeprogressWidget<progress></progress>
sliderA control that allows the user to select a value from within a given rangeinputWidget<input type="range">
spinbutton:A form of range that expects the user to select from among discrete choicesinputWidget<input type="number">

Next time you don't know what role your component elements have, refer to this table. I know i will

Roles not included in the table

Roles without default HTML element

  • grid
  • gridcell
  • dialog
  • alert
  • alertdialog
  • combobox
  • menu
  • menubar
  • menuitem
  • menuitemcheckbox
  • menuitemradio
  • application
  • document
  • feed
  • tree
  • treegrid
  • treeitem
  • tab
  • tablist
  • tabpanel
  • log
  • marquee
  • note
  • scrollbar
  • status
  • switch
  • timer
  • toolbar
  • tooltip

Abstract roles

Abstract roles are included for completeness of documentation. They should not be used by web authors.

  • command
  • composite
  • input
  • landmark
  • range
  • roletype
  • section
  • sectionhead
  • select
  • structure
  • widget
  • window

Other roles

  • math role for <math> element cannot by queried by testing-library
  • presentation and none - removes an element's implicit ARIA semantics from being exposed to the accessibility tree
  • comment - a landmark role that is currently in draft proposal
  • mark role for <mark> is currently being drafted also
  • banner - for <header> element which is not really you test for in your React applications
  • generic - it's a default role for:
    • <div> and <span> elements
    • <a> or <area> without href
    • <b>, <i>
    • <bdi>, <bdo>
    • <body>
    • <header>
    • <data>
    • <hgroup>
    • <pre>
    • <q>
    • <samp>
    • <small>
    • <u>
  • meter - role for <meter> element is not included in the table because it is not supported by testing-library
  • suggestion - role that is currently being drafted


Share via twitterShare Via Linkedin