Loading Developer Playground

Loading ...

Skip to main content
ARIA ROLEโ€ขLandmark Roles

complementary

A supporting section of the document that is designed to be complementary to the main content. Common uses include sidebars, related articles, author information, pull quotes, and advertising.

Landmark RoleImplicit on <aside>WCAG 2.2
๐ŸŽฏ

Purpose

Identifies supporting content that complements the main content but can be understood independently

๐Ÿ“ฑ

HTML Equivalent

Automatically applied to <aside> elements

โ™ฟ

Screen Reader

Announced as "complementary" or "aside" landmark for quick navigation

๐Ÿ’กWhen to Use

1

Sidebar Content

Related articles, quick links, additional resources, or widgets

2

Author Information

Biography, credentials, or author details alongside articles

3

Related Content

Pull quotes, glossaries, or supplementary information

4

Advertisement Sections

Clearly marked advertising content separate from main content

๐Ÿ’ปCode Examples

Basic Complementary Role

Using the complementary role on an aside element

<!-- Using semantic HTML (Preferred) -->
<aside>
  <h2>Related Articles</h2>
  <ul>
    <li><a href="/article1">Understanding ARIA</a></li>
    <li><a href="/article2">Accessibility Best Practices</a></li>
    <li><a href="/article3">Semantic HTML Guide</a></li>
  </ul>
</aside>

<!-- Using role="complementary" explicitly -->
<div role="complementary" aria-labelledby="sidebar-heading">
  <h2 id="sidebar-heading">Quick Links</h2>
  <nav>
    <a href="/docs">Documentation</a>
    <a href="/tutorials">Tutorials</a>
    <a href="/examples">Examples</a>
  </nav>
</div>

Sidebar with Multiple Sections

A complete sidebar with related content, ads, and social links

<aside aria-labelledby="sidebar-title">
  <h2 id="sidebar-title" class="sr-only">Sidebar</h2>
  
  <!-- Related Posts -->
  <section>
    <h3>Related Posts</h3>
    <ul>
      <li><a href="/post1">Getting Started with React</a></li>
      <li><a href="/post2">Advanced TypeScript Patterns</a></li>
      <li><a href="/post3">CSS Grid Mastery</a></li>
    </ul>
  </section>
  
  <!-- Newsletter Signup -->
  <section>
    <h3>Subscribe to Newsletter</h3>
    <form>
      <label for="email">Email Address</label>
      <input type="email" id="email" name="email" required />
      <button type="submit">Subscribe</button>
    </form>
  </section>
  
  <!-- Social Links -->
  <section>
    <h3>Follow Us</h3>
    <ul>
      <li><a href="https://twitter.com/example">Twitter</a></li>
      <li><a href="https://github.com/example">GitHub</a></li>
      <li><a href="https://linkedin.com/company/example">LinkedIn</a></li>
    </ul>
  </section>
</aside>

Multiple Complementary Regions

Using multiple complementary regions with unique labels

<main>
  <article>
    <h1>Main Article Content</h1>
    <p>Article text goes here...</p>
  </article>
  
  <!-- First complementary region -->
  <aside aria-label="Author information">
    <h2>About the Author</h2>
    <img src="author.jpg" alt="Jane Doe" />
    <p>Jane is a web developer with 10 years of experience...</p>
  </aside>
  
  <!-- Second complementary region -->
  <aside aria-label="Related resources">
    <h2>Additional Resources</h2>
    <ul>
      <li><a href="/resource1">Resource 1</a></li>
      <li><a href="/resource2">Resource 2</a></li>
    </ul>
  </aside>
</main>

React Component Example

Implementing complementary role in a React sidebar component

import { FC } from 'react'

interface SidebarProps {
  relatedPosts: Array<{ id: string; title: string; url: string }>
  categories: Array<{ id: string; name: string; count: number }>
}

export const Sidebar: FC<SidebarProps> = ({ relatedPosts, categories }) => {
  return (
    <aside 
      className="sidebar"
      aria-label="Sidebar with related content"
    >
      {/* Related Posts */}
      <section className="sidebar-section">
        <h2 className="sidebar-heading">Related Posts</h2>
        <ul className="post-list">
          {relatedPosts.map((post) => (
            <li key={post.id}>
              <a href={post.url}>{post.title}</a>
            </li>
          ))}
        </ul>
      </section>

      {/* Categories */}
      <section className="sidebar-section">
        <h2 className="sidebar-heading">Categories</h2>
        <ul className="category-list">
          {categories.map((category) => (
            <li key={category.id}>
              <a href={`/category/${category.id}`}>
                {category.name} ({category.count})
              </a>
            </li>
          ))}
        </ul>
      </section>
    </aside>
  )
}

โญBest Practices

โœ“

Use Semantic HTML

Prefer using the <aside> element. It automatically has the complementary role when used outside of main content.

๐Ÿท๏ธ

Add Descriptive Labels

Use aria-label or aria-labelledby when you have multiple complementary regions to distinguish them.

๐Ÿ“

Position Appropriately

Place complementary content beside or after the main content, never before it in the DOM.

๐Ÿ“

Keep Content Related

Content should support the main content. Common uses: sidebars, pull quotes, related articles, author info.

๐Ÿ”ข

Multiple Regions OK

You can have multiple complementary regions on a page, but each should have a unique label.

โ™ฟ

Include Headings

Always include a heading (h2-h6) as the first child to provide context and structure.

โš ๏ธCommon Mistakes to Avoid

Missing Labels for Multiple Regions

โŒ Wrong

Having multiple complementary regions without unique labels

<aside>Author Info</aside>
<aside>Related Posts</aside> โŒ
โœ“ Correct

Provide unique aria-label for each complementary region

<aside aria-label="Author information">
  Author Info
</aside>
<aside aria-label="Related posts">
  Related Posts
</aside> โœ“

Using for Main Navigation

โŒ Wrong

Using complementary for primary site navigation

<aside role="complementary">
  <nav>
    <a href="/">Home</a>
    <a href="/about">About</a>
  </nav>
</aside> โŒ
โœ“ Correct

Use navigation role for navigation menus, complementary for supporting content

<nav aria-label="Main navigation">
  <a href="/">Home</a>
  <a href="/about">About</a>
</nav> โœ“

No Heading

โŒ Wrong

Omitting a heading in the complementary region

<aside>
  <ul>
    <li>Item 1</li>
    <li>Item 2</li>
  </ul>
</aside> โŒ
โœ“ Correct

Always include a heading to describe the content

<aside aria-labelledby="related-heading">
  <h2 id="related-heading">Related Items</h2>
  <ul>
    <li>Item 1</li>
    <li>Item 2</li>
  </ul>
</aside> โœ“

๐Ÿ”—Related ARIA Attributes

aria-label

Provide a label for the complementary region, especially when multiple regions exist

<aside aria-label="Related articles">
Learn More โ†’

aria-labelledby

Reference a visible heading that labels the complementary region

<aside aria-labelledby="sidebar-title">
Learn More โ†’

โ™ฟAccessibility Support

๐ŸŽค

Screen Readers

Complementary landmarks are announced by screen readers, allowing users to quickly navigate to supporting content using landmark navigation (e.g., "D" key in NVDA/JAWS for landmarks).

โŒจ๏ธ

Keyboard Navigation

Users can jump directly to complementary regions using keyboard shortcuts, making it easier to access sidebar content and related information.

๐ŸŒ

Browser Support

Universally supported across all modern browsers and assistive technologies. The semantic <aside> element provides automatic complementary role mapping.