HTML Guide

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>

The <article> element can be used to define complete, self-contained compositions of a document, for example blog posts. Consider using a heading element (any of <h2> to </h6>) to present each article.

Example:

<h1>Our blog</h1>
<article>
  <h2>How to validate accessibility</h2>
  <p>Use Rocket Validator for a in-depth scan</p>
</article>
<article>
  <h2>How to monitor sites for accessibility</h2>
  <p>Define schedules in Rocket Validator</p>
</article>

Using role="article" on a <section> element is invalid because article is not a permitted value for the role attribute.

The role attribute in HTML is used to define ARIA roles that describe the purpose of an element for assistive technologies. Only specific, predefined ARIA roles are valid per the WAI-ARIA specification. article is not a recognized ARIA role—use document or other appropriate roles instead, or omit the role attribute entirely. The <article> and <section> elements already have implicit roles, so manual role assignment is rarely necessary or useful for these elements.

Valid uses:

• Use <article> without a role attribute for content that is self-contained and intended to be independently distributable or reusable.
• Use <section> for grouping related content and omit the role attribute unless a specific ARIA landmark role is needed (such as region).

Example: use <article> for standalone content

<article>
  <h2>News headline</h2>
  <p>News content goes here.</p>
</article>

Example: use <section> without a role attribute for generic grouping

<section>
  <h2>Introduction</h2>
  <p>Section content.</p>
</section>

Using the ARIA role value listitem on an article element is invalid.

The article element is a landmark with an implicit role of article, and ARIA requires roles to match the element’s semantics. The listitem role is only valid for elements that are direct children of a list-type container with role list or group, or native lists like ul/ol. If you want an article in a list, wrap each article in a proper list container and either rely on native semantics (ul/ol) or use a neutral container with an explicit role="list". Avoid overriding landmark elements with unrelated roles. Use the role attribute only when necessary, and prefer native HTML semantics.

HTML Examples

Invalid: article with role=”listitem”

<article role="listitem">
  <h2>News item</h2>
  <p>Details...</p>
</article>

Valid options

<!-- Option A: Use native list semantics -->

<ul>
  <li>
    <article>
      <h2>News item</h2>
      <p>Details...</p>
    </article>
  </li>
  <li>
    <article>
      <h2>Another item</h2>
      <p>More details...</p>
    </article>
  </li>
</ul>

<!-- Option B: ARIA list with neutral containers -->

<div role="list">
  <div role="listitem">
    <article>
      <h2>News item</h2>
      <p>Details...</p>
    </article>
  </div>
  <div role="listitem">
    <article>
      <h2>Another item</h2>
      <p>More details...</p>
    </article>
  </div>
</div>

The role="tabpanel" attribute is not permitted on the article element according to W3C and WHATWG HTML specifications.

The role attribute helps describe the purpose of an element for assistive technologies. The value tabpanel indicates a section of a tab interface and should be used only with elements suited to that role—typically generic containers like div or section, not article. The article element has its own landmark meaning and should not be used for widgets such as tab panels.

Correct usage:

• Use role="tabpanel" on a div or section element.
• Use role="tablist" on the container of the tabs.
• Use role="tab" on each tab.

Incorrect:

<article role="tabpanel" id="panel1">
  Tab panel content here.
</article>

Correct:

<div role="tabpanel" id="panel1">
  Tab panel content here.
</div>

Full example:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Tabpanel Example</title>
</head>
<body>
  <div role="tablist">
    <button role="tab" aria-controls="panel1" aria-selected="true">Tab 1</button>
    <button role="tab" aria-controls="panel2" aria-selected="false">Tab 2</button>
  </div>
  <div role="tabpanel" id="panel1">
    Tab panel content here.
  </div>
  <div role="tabpanel" id="panel2" hidden>
    Tab panel 2 content here.
  </div>
</body>
</html>

Replace the article element with a div or section when assigning the tabpanel role to ensure your markup is valid and accessible.

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>

A main element cannot be nested within another main element.

The main element represents the primary content of a document or application, and there must be only one per page, not placed inside another main. The main element must not be used as a descendant of another main element. This is important for accessibility, semantic correctness, and helps screen readers correctly identify the main content region.

Invalid example (nested main):

<main>
  <h1>Welcome</h1>
  <main>
    <p>This nested main element is invalid.</p>
  </main>
</main>

Valid example (single main only):

<main>
  <h1>Welcome</h1>
  <section>
    <p>This section is valid and can be placed inside main.</p>
  </section>
</main>

If you need to divide the main content, use sectioning elements like section, article, or div inside a single main element, but never nest main inside main.

The main element represents the dominant contents of the document, so it should not be contained within another section.

A document must not have more than one main element that does not have the hidden attribute specified.

A hierarchically correct main element is one whose ancestor elements are limited to html, body, div, form without an accessible name, and autonomous custom elements. Each main element must be a hierarchically correct main element.

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>