HTML Guide

The autocomplete attribute is used to control if the browser can provide assistance in filling out form field values, and it only makes sense for visible, not hidden, inputs.

It is available on <input> elements that take a text or numeric value as input, <textarea> elements, <select> elements, and <form> elements.

To fix this issue, you can remove the autocomplete attribute from the input element with type=hidden. Here is an example:

<!-- Wrong code -->

<input type="hidden" name="phone" value="12345" autcomplete="off">

<!-- Correct code -->

<input type="hidden" name="phone" value="12345">

The role attribute value combobox is not valid on an input element according to the W3C HTML standard.

The role="combobox" is valid only when applied to an element that acts as a container for the combo box widget, usually a div or similar element, and not directly to a native HTML input. Native input elements of type "text" or "search" already have implicit roles and accessibility semantics. To create an accessible combobox, wrap the input inside a container element with role="combobox" and use appropriate ARIA attributes.

Incorrect Implementation:

<input type="text" role="combobox" aria-autocomplete="list">

Correct Implementation:

<div role="combobox" aria-haspopup="listbox" aria-owns="suggestions" aria-expanded="false">
  <input type="text" aria-autocomplete="list" aria-controls="suggestions">
</div>
<ul id="suggestions" role="listbox">
  <li role="option" id="option1">Option 1</li>
  <li role="option" id="option2">Option 2</li>
</ul>

Explanation of attributes:

• role="combobox": Applied to the container (<div>) to define the accessible widget.
• aria-haspopup="listbox": Indicates the presence of a list of suggestions.
• aria-owns / aria-controls: Connects the input and suggestion list.
• aria-expanded: Denotes whether the suggestion list is visible.
• aria-autocomplete: Defines the autocomplete behavior.

This markup ensures better accessibility and passes W3C validation.

<input> elements can’t have a search role. Instead, try with <input type="search">.

<input> elements of type search are text fields designed for the user to enter search queries into. These are functionally identical to text inputs, but may be styled differently depending on the user agent.

The search role is a landmark. Landmarks can be used by assistive technology to quickly identify and navigate to large sections of the document. The search role is added to the container element that encompasses the items and objects that, as a whole, combine to create search functionality. When a <form> is a search form, use the search role on the form.

Example of a search form:

<form role="search">
  <label for="search-input">Search this site</label>
  <input type="search" id="search-input" name="search">
  <input value="Submit" type="submit">
</form>

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 aria-hidden attribute is redundat on an input of type hidden, so it should be removed.

Example:

<!-- Instead of this... -->

<input type="hidden" aria-hidden="true" id="month" value="10" />

<!-- You can just use this -->

<input type="hidden" id="month"  value="10" />

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>

There can only be one visible <main> element in a document. If more are needed (for example for switching between them with JavaScript), only one can be visible, the others should be hidden toggling the hidden attribute.

Example of 2 main elements, where only one is visible:

<main>
  <h1>Active main element</h1>
<!-- content -->

</main>

<main hidden>
  <h1>Hidden main element</h1>
<!-- content -->

</main>

An a element with both an href attribute and aria-disabled="true" is invalid; either remove aria-disabled or the href attribute.

The aria-disabled attribute is used for interactive elements to indicate that the element is perceivable as disabled by assistive technologies. However, using aria-disabled="true" in combination with an href attribute on an a element is not valid, because the link remains actionable for both user agents and assistive devices. Instead, if a link should appear disabled, you should remove the href attribute, use CSS for styling, and optionally use aria-disabled="true". If you need the element to always act as a link, avoid aria-disabled and control user access through application logic.

Incorrect:

<a href="page.html" aria-disabled="true">Visit Page</a>

Correct—Option 1: Remove aria-disabled, keep link active

<a href="page.html">Visit Page</a>

Correct—Option 2: Remove href, use aria-disabled, for non-actionable item

<a aria-disabled="true" tabindex="-1" style="pointer-events: none; color: gray;">Visit Page</a>

In the second correct example, setting tabindex="-1" prevents keyboard navigation, and pointer-events: none; makes the link unclickable, while aria-disabled="true" makes the disabled state accessible.

A role="columnheader" element must be a child of or associated with a role="row" element.

In HTML, ARIA roles such as columnheader are used to improve accessibility for assistive technologies. According to the ARIA specification, a columnheader role should appear inside an element with role="row", which itself should be inside an element with role="table" or role="grid". This structure mimics how native tables are constructed with <th> elements inside <tr>s.

Correct structure:

• role="table" or role="grid" contains one or more elements with role="row".
• Each role="row" contains one or more elements with role="columnheader" (or role="cell").

Example using ARIA roles for a simple table:

<div role="table" aria-label="Sample Table">
  <div role="row">
    <div role="columnheader">Name</div>
    <div role="columnheader">Age</div>
  </div>
  <div role="row">
    <div role="cell">Alice</div>
    <div role="cell">30</div>
  </div>
</div>

Best practice:
Whenever possible, use native table elements, which have built-in roles and accessibility, reducing the chance of ARIA misuse.

Example using native table markup:

<table>
  <tr>
    <th>Name</th>
    <th>Age</th>
  </tr>
  <tr>
    <td>Alice</td>
    <td>30</td>
  </tr>
</table>

Ensure that any element with role="columnheader" is always contained within a parent with role="row". Avoid placing role="columnheader" directly inside a container without the appropriate role="row" ancestor.

To fix this issue, ensure that an element with role="listitem" is contained within an element with role="list" or role="group". Here’s how you can structure your HTML correctly:

Incorrect Example

<div role="listitem">Item 1</div>
<div role="listitem">Item 2</div>

Correct Example

<div role="list">
  <div role="listitem">Item 1</div>
  <div role="listitem">Item 2</div>
</div>

Alternatively, you can use role="group" if it’s a nested list.

Correct Example with Nested List

<div role="list">
  <div role="listitem">Item 1</div>
  <div role="group">
    <div role="listitem">Item 1.1</div>
    <div role="listitem">Item 1.2</div>
  </div>
  <div role="listitem">Item 2</div>
</div>

This ensures that the role="listitem" elements are correctly contained.