HTML Guide
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.
Learn more:
Related W3C validator issues
According to the ARIA specification, the attribute aria-rowspan is expected to have a positive integer value. A positive integer is a whole number greater than zero.
Explanation
- aria-rowspan: This attribute is used in ARIA-enabled tables to indicate how many rows a cell should span within its row group. It is often used in elements like gridcell or rowheader within roles that imply grid-like structures, such as grid or treegrid.
Example of Incorrect Usage
<div role="gridcell" aria-rowspan="0">Content</div>
In this example, aria-rowspan is set to "0", which is not a valid positive integer.
Correct Usage
To resolve the issue, you should specify a positive integer. For example, if the cell should span one row, you can write:
<div role="gridcell" aria-rowspan="1">Content</div>
If the cell should span multiple rows, adjust the number accordingly:
<div role="gridcell" aria-rowspan="2">Content</div>
Considerations
- Make sure the role attribute is correctly associated with an element that can logically have a row and grid structure, such as gridcell.
- Ensure that the aria-rowspan value aligns with the structure of your grid or table, representing the actual number of rows that the element is spanning.
The dialog element does not require or permit a role="dialog" attribute according to HTML standards.
The <dialog> element has an implicit ARIA role of dialog, so adding role="dialog" is redundant and not valid per the specification. Instead, simply use the <dialog> element without an explicit role attribute.
Details:
According to the WHATWG HTML standard and ARIA specification, native <dialog> elements automatically have the correct role. Adding role="dialog" can cause HTML validation errors, as the validator interprets this as a misuse or redundancy.
Correct usage:
<dialog>
<p>This is a dialog box.</p>
<button>Close</button>
</dialog>
Incorrect usage (causes validation error):
<dialog role="dialog">
<p>This is a dialog box.</p>
<button>Close</button>
</dialog>
Removing the role="dialog" attribute resolves the W3C validation issue while maintaining accessibility.
Empty aria-controls attribute values are invalid; the attribute must reference the id of one or more elements.
The aria-controls attribute is used to indicate that the element controls the referenced element(s) by their id. According to the ARIA specification and W3C HTML standard, the attribute must contain at least one valid id value, and cannot be an empty string. Leaving aria-controls="" triggers a validation error.
Correct Usage:
- Assign an id to the element being controlled.
- Set the aria-controls attribute to match that id.
- Remove aria-controls entirely if not necessary.
Incorrect Example:
<a href="#" aria-controls="">Toggle</a>
Corrected Example:
<div id="details">Some details...</div>
<a href="#" aria-controls="details">Toggle</a>
If no element is being controlled:
<a href="#">Toggle</a>
The icon value for attribute role is not a valid ARIA role.
ARIA Roles: Overview
ARIA roles are used to enhance accessibility by clearly defining the role and purpose of an element for assistive technologies. However, there are defined roles that you need to adhere to:
- Standard roles include button, checkbox, alert, dialog, img, etc.
- There is no ARIA role named icon.
Solution
To fix the issue, you need to use a valid ARIA role that accurately describes the purpose of the span element. If your intention is to convey that the span contains an icon, you might want to reconsider whether you need a role at all. Often, purely decorative elements should not have a role, or you might use an img role if it conveys a meaningful image.
Here’s how you can address this:
-
No ARIA role (if purely decorative): If the icon is purely decorative and does not add meaningful content to your page, you should remove the role attribute entirely.
<span class="icon"></span>
-
Using img role (if it represents an image): If the span represents an image or an icon that conveys meaningful information, you can use role="img" and provide a proper aria-label.
<span class="icon" role="img" aria-label="Icon Description"></span>
-
Using an appropriate role (if interactive): If the icon is part of an interactive element, you might need a different role. For instance, if the icon is inside a button:
<button> <span class="icon" aria-hidden="true"></span> Button text </button>
Here, aria-hidden="true" is used to hide the decorative icon from screen readers as the text provides the necessary context.
sidebar is not a valid value for the role attribute according to the ARIA (Accessible Rich Internet Applications) specification.
The role attribute is used to define the purpose of an element for assistive technologies. Only certain predefined values are valid, such as navigation, complementary, main, banner, contentinfo, and others. There is no sidebar role in the ARIA or HTML specification. If you wish to indicate a sidebar, you should use the complementary role, which is intended for content that is tangentially related to the main content, such as a sidebar.
Incorrect Example:
<div role="sidebar">
<!-- Sidebar content -->
</div>
Correct Example:
<div role="complementary">
<!-- Sidebar content -->
</div>
Alternatively, you can use the aside element, which conveys the same meaning and does not require an explicit role attribute:
<aside>
<!-- Sidebar content -->
</aside>
Using either the role="complementary" on a generic container or the semantic <aside> element ensures your HTML is valid and accessible.
sidebar is not a valid value for the role attribute according to the ARIA (Accessible Rich Internet Applications) specification.
The role attribute is used to define the purpose of an element for assistive technologies. Only certain predefined values are valid, such as navigation, complementary, main, banner, contentinfo, and others. There is no sidebar role in the ARIA or HTML specification. If you wish to indicate a sidebar, you should use the complementary role, which is intended for content that is tangentially related to the main content, such as a sidebar.
Incorrect Example:
<div role="sidebar">
<!-- Sidebar content -->
</div>
Correct Example:
<div role="complementary">
<!-- Sidebar content -->
</div>
Alternatively, you can use the aside element, which conveys the same meaning and does not require an explicit role attribute:
<aside>
<!-- Sidebar content -->
</aside>
Using either the role="complementary" on a generic container or the semantic <aside> element ensures your HTML is valid and accessible.
The rel attribute defines the relationship between a linked resource and the current document. Valid on <link>, <a>, <area>, and <form>, the supported values depend on the element on which the attribute is found.
Here’s an example of using the rel attribute to link a document to a CSS stylesheet:
<link rel="stylesheet" href="default.css" />
Here’s an example os using the rel attribute to tell search engine spiders to ignore the link relationship with another document:
<a href="https://example.com" rel="nofollow">more info</a>
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.