HTML Guide for aria

The attribute aria-hidden must have a value of "true" (without extra quotes) or "false", not "\"true\"" (with double quotes inside the value).

The aria-hidden attribute is used to indicate whether an element and its children should be accessible to assistive technologies (like screen readers). Valid values are the strings "true" or "false" (without embedded quotation marks). Using extra quotation marks causes the validator to flag a bad value because the attribute’s value is interpreted literally.

Incorrect Example:

<div aria-hidden='"true"'>This is hidden from assistive tech</div>

Correct Example:

<div aria-hidden="true">This is hidden from assistive tech</div>

or

<div aria-hidden="false">This is visible to assistive tech</div>

Remove any extra quotation marks around your attribute value to resolve the error.

The only accepted values for the aria-current property are page, step, location, date, time, true and false.

A non-null aria-current state on an element indicates that this element represents the current item within a container or set of related elements.

When you have a group of related elements, such as several links in a breadcrumb or steps in a multi-step flow, with one element in the group styled differently from the others to indicate to the sighted user that this is the current element within its group, the aria-current should be used to inform the assistive technology user what has been indicated via styling.

In its simplest form, you only need to add aria-current="true" to the element that you wish to mark as the current element of a group, for example:

<nav>
  <ol>
    <li>
      <a href="/page1">Page 1</a>
    </li>
    <li>
      <a href="/page2" aria-current="true">Page 2</a>
    </li>
    <li>
      <a href="/page3">Page 3</a>
    </li>
  </ol>
</nav>

If you can, use the values page, step, location, date or time instead of true to indicate the nature of the current element:

page

Represents the current page within a set of pages such as the link to the current document in a breadcrumb.

step

Represents the current step within a process such as the current step in an enumerated multi step checkout flow.

location

Represents the current location within an environment or context such as the image that is visually highlighted as the current component of a flow chart.

date

Represents the current date within a collection of dates such as the current date within a calendar.

time

Represents the current time within a set of times such as the current time within a timetable.

For example, here we use page instead of true.

<nav>
  <ol>
    <li>
      <a href="/page1">Page 1</a>
    </li>
    <li>
      <a href="/page2" aria-current="page">Page 2</a>
    </li>
    <li>
      <a href="/page3">Page 3</a>
    </li>
  </ol>
</nav>

If you want to indicate that an element is not the current element, you can use the false value or just skip the aria-current property entirely on the element.

Using a blank string is not a valid value for this property, so instead of this:

 <a href="/page3" aria-current="">Page 3</a>

you can use false:

 <a href="/page3" aria-current="false">Page 3</a>

or, better yet, skip the property entirely:

 <a href="/page3">Page 3</a>

The only accepted value for the aria-required property is true.

The aria-required attribute indicates that user input is required on the element before a form may be submitted.

When a semantic HTML <input>, <select>, or <textarea> must have a value, it should have the required attribute applied to it. When form controls are created using non-semantic elements, such as a <div> with a role of checkbox, the aria-required attribute should be included, with a value of true, to indicate to assistive technologies that user input is required on the element for the form to be submittable.

Example:

<div id="email_label">Email Address *</div>
<div
  role="textbox"
  contenteditable
  aria-labelledby="email_label"
  aria-required="true"
  id="email"></div>

The disabled attribute is a boolean attribute and must not have a value or should simply be present (disabled or disabled=""). Boolean attributes like disabled indicate presence by their occurrence alone and should not include explicit values.

Incorrect usage:

<input type="text" disabled="yes">
<input type="text" disabled="true">
<input type="text" disabled="false">

Correct usage:

<input type="text" disabled>
<input type="text" disabled="">

Only the presence of the disabled attribute disables the input. The value, if given, is ignored by the browser but causes validation problems if specified incorrectly. For W3C compliance, simply include the disabled attribute without specifying a value.

Although using <input type="text" disabled="disabled"> might still be marked as valid by the W3C Validator, the general recommendation for boolean attributes is to not pass any value.

The boolean required attribute, if present, indicates that the user must specify a value for the input before the owning form can be submitted.

If this property is not present, the input will be considered as optional. To mark an input as required, it’s enough to include the property without any value, or pass it the required value as in these examples:

Example:

<input type="text" required>
<input type="text" required="required">

An element is using ARIA attributes, but its role has not been defined. ARIA defines semantics that can be applied to elements, with these divided into roles (defining a type of user interface element) and states and properties that are supported by a role. Authors must assign an ARIA role and the appropriate states and properties to an element during its life-cycle, unless the element already has appropriate ARIA semantics (via use of an appropriate HTML element). Examples:

<!-- This div uses ARIA but its role is not clear, so it's invalid. -->

<div aria-expanded="true">...</div>

<!-- This div defines clearly its role, so it's valid. -->

<div role="navigation" aria-expanded="true">...</div>

<!-- Nav elements have an implicit navigation role so we don't need the role attribute. -->

<nav aria-expanded="true">...</nav>

The aria-controls attribute identifies an element or elements in the same document whose contents or presence are controlled by the current element. It must point to existing elements by their ID. Check that the IDs contained in that property exist within the same document.

ARIA can express semantic relationships between elements that extend the standard parent/child connection, such as a custom scrollbar that controls a specific region, for example:

<div role="scrollbar" aria-controls="main"></div>
<div id="main">
  . . .
</div>

The aria-describedby attribute is used to indicate the IDs of the elements that describe the object. It should reference an existing ID on the same document, but that id was not found.

The article role indicates a section of a page that could easily stand on its own on a page, in a document, or on a website, is implicit when using the <article> tag.

This role indicates a section of a page that could easily stand on its own on a page, in a document, or on a website. It is usually set on related content items such as comments, forum posts, newspaper articles or other items grouped together on one page. It can be added to generic elements like <div> to convey this role, for example:

<div role="article">
  <h2>Heading</h2>
  <p>Content...</p>
</div>

Instead of using this role, it’s preferrable to use the native <article> element like this:

<article>
  <h2>Heading</h2>
  <p>Content...</p>
</article>

The <header> HTML element represents introductory content, typically a group of introductory or navigational aids, and has an implicit role of banner, so specifying this role is redundant.

The following example represents a banner using the role attribute:

<div role="banner">
  <img src="companylogo.svg" alt="my company name" />
  <h1>Title</h1>
  <p>Subtitle</p>
</div>

By default, the HTML5 <header> element has an identical meaning to the banner landmark, unless it is a descendant of <aside>, <article>, <main>, <nav>, or <section>, at which point <header> is the heading for that section and not the equivalent of the site-wide banner.

This example uses the <header> element instead of the banner role:

<header>
  <img src="companylogo.svg" alt="my company name" />
  <h1>Title</h1>
  <p>Subtitle</p>
</header>

The button role is used to make an element appear as a button control to a screen reader and can be applied to otherwise non-interactive elements like <div>. If you’re already using a <button> element, then it’s redundant to apply it the role button, as that’s implicit.

<!-- Instead of this -->

<button role="button">Buy</button>

<!-- Do this -->

<button>Buy</button>

The button role is used to make an element appear as a button control to a screen reader and can be applied to otherwise non-interactive elements like <div>. If you’re already using an <input> element whose type is submit, then it’s redundant to apply it the role button, as that’s implicit.

<!-- Instead of this -->

<input type="submit" role="button">Buy</button>

<!-- Do this -->

<input type="submit">Buy</button>

The <summary> HTML element specifies a clickable summary, caption, or legend for a <details> element’s disclosure box. As the <summary> element has an implicit button role, it’s not needed to include it explicitly.

Here’s an example, clicking the <summary> element toggles the state of the parent <details> element open and closed.

<details>
    <summary>I have keys but no doors. I have space but no room. You can enter but can’t leave. What am I?</summary>
    A keyboard.
</details>

The <footer> element represents a footer for its nearest sectioning content, and has an implicit role of contentinfo, so specifying this role is redundant.

The following example marks a <div> as a footer specifying its role:

<div role="contentinfo">
  <h2>Footer</h2>
<!-- footer content -->

</div>

Using the <footer> element instead is recommended:

<footer>
  <h2>Footer</h2>
<!-- footer content -->

</footer>

The role="dialog" attribute is redundant when used on a <dialog> element because <dialog> has an implicit dialog role by default.

According to the WHATWG HTML living standard and ARIA in HTML, the <dialog> element already has the appropriate semantics for assistive technologies, so explicitly adding role="dialog" is unnecessary and causes warnings in validators.

Incorrect usage:

<dialog role="dialog">
  This is a dialog box.
</dialog>

Correct usage:

<dialog>
  This is a dialog box.
</dialog>

Simply remove the role attribute from the <dialog> element to resolve the warning.

A button element is not allowed to contain other button elements, or other elements with role=button.

The button role identifies an element as a button to assistive technology such as screen readers. A button is a widget used to perform actions such as submitting a form, opening a dialog, canceling an action, or performing a command such as inserting a new record or displaying information. Adding role="button" tells assistive technology that the element is a button but provides no button functionality

This W3C HTML Validator issue indicates that you have assigned a role="group" attribute to a <fieldset> element. In HTML, the <fieldset> element already has an implicit role of group so it’s redundant and unnecessary to explicitly specify it.

To resolve this issue, you simply need to remove the role="group" attribute from the <fieldset> element.

Example of the Issue

Here is an example of problematic HTML:

<form>
  <fieldset role="group">
      <legend>Personal Information</legend>
      <label for="name">Name:</label>
      <input type="text" id="name" name="name">
      <br>
      <label for="age">Age:</label>
      <input type="number" id="age" name="age">
  </fieldset>
</form>

Fixed HTML

To fix this issue, remove the role="group" attribute from the <fieldset> element:

<form>
  <fieldset>
      <legend>Personal Information</legend>
      <label for="name">Name:</label>
      <input type="text" id="name" name="name">
      <br>
      <label for="age">Age:</label>
      <input type="number" id="age" name="age">
  </fieldset>
</form>

The heading role defines this element as a heading to a page or section, and is implicit in tags <h1> to <h6>.

The heading role indicates to assistive technologies that this element should be treated like a heading. Screen readers would read the text and indicate that it is formatted like a heading.

This ARIA role is only needed to add that role to a generic element like <div>, for example:

<div role="heading" aria-level="1">This is a main page heading</div>

This defines the text in the <div> to be the main heading of the page, indicated by being level 1 via the aria-level attribute. Opt for using the <h1> (thru <h6>) element instead:

<h1>This is a main page heading</h1>

A single <img> element is used to embed an image, so adding the img role to it is redundant.

The ARIA img role can be used to identify multiple elements inside page content that should be considered as a single image. These elements could be images, code snippets, text, emojis, or other content that can be combined to deliver information in a visual manner, for example:

<div role="img" aria-label="Description of the overall image">
  <img src="graphic1.png" alt="">
  <img src="graphic2.png">
</div>

A <li> element is used to define an item of a list, so adding the listitem role to it is redundant.

The ARIA listitem role can be used to identify an item inside a list of items. It is normally used in conjunction with the list role, which is used to identify a list container.

<section role="list">
  <div role="listitem">List item 1</div>
  <div role="listitem">List item 2</div>
  <div role="listitem">List item 3</div>
</section>

When possible, you should use the appropriate semantic HTML elements to mark up a list and its list items — <ul> or <ol>, and <li>. For example:

<ul>
  <li>List item 1</li>
  <li>List item 2</li>
  <li>List item 3</li>
</ul>

The main landmark role is used to indicate the primary content of a document. It can be added to an element by using role="main", but instead it’s preferable to just use the <main> element. In that case, it’s unnecessary to make the main role explicit. Examples:

<div role="main">
<!-- this is a valid way to define a main role -->

</div>

<main>
<!-- but this is shorter and uses correct semantic HTML  -->

</main>

The navigation landmark role is used to identify major groups of links used for navigating through a website or page content. It can be added to an element that contains navigation links by using role="navigation", but instead it’s preferable to just use the <nav> element. In that case, it’s unnecessary to make the navigation role explicit.

Examples:

<div role="navigation">
<!-- this is a valid way to define a navigation role -->

</div>

<nav>
<!-- but this is shorter and uses correct semantic HTML  -->

</nav>

A section element automatically defines a landmark region, so adding role="region" is redundant.

According to the HTML specification and WAI-ARIA guidelines, sectioning elements such as section, nav, article, and aside already have implicit landmark roles. Adding an explicit role="region" to a section does not change its semantics, and HTML validators will warn against this unnecessary usage.

Incorrect Example:

<section role="region">
  <h2>Contact Information</h2>
  <p>Email us at info@example.com</p>
</section>

Correct Example:

<section>
  <h2>Contact Information</h2>
  <p>Email us at info@example.com</p>
</section>

If a region of the page does not have an accessible name and you want it to be a landmark, add a heading element (<h1>-<h6>) as the first child to label the region for assistive technologies. Avoid adding redundant ARIA role attributes to native landmark elements for better accessibility and HTML validation.

The role="searchbox" attribute is redundant on an <input type="search"> without a list attribute and should be removed.

According to the HTML and ARIA specifications, an <input> element with type="search" is already recognized by assistive technologies as a search box. Adding role="searchbox" does not provide additional meaning and is considered unnecessary and potentially confusing by validators.

Incorrect usage:

<input type="search" role="searchbox" placeholder="Search...">

Correct usage:

<input type="search" placeholder="Search...">

The textbox role, used to identify an element that allows the input of free-form text, is unnecessary for an <input> element of type text when it doesn’t have a list attribute.