ARIA Roles and Attributes

The First Rule of ARIA

If you can use a native HTML element or attribute with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so.

<!-- HTML5 semantic element - preferred approach -->
<header>...</header>

<!-- Equivalent ARIA role - use when HTML5 element isn't possible -->
<div role="banner">...</div>

Common Widget Roles

• button: An interactive element that triggers an action
• checkbox: A checkable input that has three possible values
• tablist, tab, tabpanel: Used together for a tabbed interface
• combobox: Input that controls another element that can dynamically pop up to help the user
• menu, menuitem: A set of menu options
• progressbar: Element that displays the progress of a task
• slider: Input where the user selects a value from a range

Common Document Structure Roles

• article: A complete or self-contained composition
• definition: A definition of a term or concept
• directory: A list of references, such as a table of contents
• list, listitem: Used for lists of items
• presentation: Element should be ignored by assistive technology (purely decorative)

<!-- Using aria-label -->
<button aria-label="Close dialog">×</button>

<!-- Using aria-labelledby to reference another element -->
<div id="heading">Weather Forecast</div>
<div role="region" aria-labelledby="heading">
  <!-- Weather content -->
</div>

<!-- Using aria-describedby for additional description -->
<input type="password" aria-describedby="password-requirements">
<p id="password-requirements">Password must be at least 8 characters and include a number.</p>

<!-- Expanded state for dropdown menus, accordions, etc. -->
<button aria-expanded="false" aria-controls="dropdown-content">Show Options</button>
<ul id="dropdown-content" hidden>
  <li>Option 1</li>
  <li>Option 2</li>
</ul>

<!-- Selected state for custom controls -->
<div role="tablist">
  <button role="tab" aria-selected="true" id="tab1">Tab 1</button>
  <button role="tab" aria-selected="false" id="tab2">Tab 2</button>
</div>

<!-- Checked state for custom checkboxes or radio buttons -->
<div role="checkbox" aria-checked="true" tabindex="0">
  Enable notifications
</div>

• aria-hidden="true": Element is not visible to assistive technologies
• aria-disabled="true": Element is perceivable but disabled
• aria-required="true": User input is required on the element
• aria-current="page": Indicates the current item within a set (e.g., current page in navigation)
• aria-busy="true": Element is being modified and assistive technologies may want to wait
• aria-live="polite|assertive|off": Indicates how assistive technologies should announce updates

<div class="tabs-container">
  <div role="tablist" aria-label="Programming languages">
    <button role="tab" 
            aria-selected="true" 
            aria-controls="panel-js" 
            id="tab-js">
      JavaScript
    </button>
    <button role="tab" 
            aria-selected="false" 
            aria-controls="panel-python" 
            id="tab-python">
      Python
    </button>
    <button role="tab" 
            aria-selected="false" 
            aria-controls="panel-php" 
            id="tab-php">
      PHP
    </button>
  </div>
  
  <div role="tabpanel" 
       id="panel-js" 
       aria-labelledby="tab-js">
    JavaScript content here...
  </div>
  
  <div role="tabpanel" 
       id="panel-python" 
       aria-labelledby="tab-python" 
       hidden>
    Python content here...
  </div>
  
  <div role="tabpanel" 
       id="panel-php" 
       aria-labelledby="tab-php" 
       hidden>
    PHP content here...
  </div>
</div>

<div class="accordion">
  <h3>
    <button aria-expanded="false" 
            aria-controls="section1-content" 
            id="section1-header">
      Section 1
    </button>
  </h3>
  <div id="section1-content" 
       role="region" 
       aria-labelledby="section1-header" 
       hidden>
    Content for section 1...
  </div>
  
  <h3>
    <button aria-expanded="false" 
            aria-controls="section2-content" 
            id="section2-header">
      Section 2
    </button>
  </h3>
  <div id="section2-content" 
       role="region" 
       aria-labelledby="section2-header" 
       hidden>
    Content for section 2...
  </div>
</div>

<!-- Button to open the dialog -->
<button onclick="openDialog()">Open Dialog</button>

<!-- The dialog itself -->
<div role="dialog" 
     aria-labelledby="dialog-title" 
     aria-describedby="dialog-desc" 
     aria-modal="true" 
     id="my-dialog" 
     hidden>
  
  <div role="document">
    <h2 id="dialog-title">Confirm Action</h2>
    <p id="dialog-desc">Are you sure you want to continue?</p>
    
    <div class="dialog-buttons">
      <button onclick="cancelDialog()">Cancel</button>
      <button onclick="confirmDialog()">Confirm</button>
    </div>
    
    <button aria-label="Close dialog" 
            onclick="closeDialog()" 
            class="close-button">
      ×
    </button>
  </div>
</div>

<!-- Polite announcements (won't interrupt current speech) -->
<div aria-live="polite">
  Your settings have been saved successfully.
</div>

<!-- Assertive announcements (may interrupt current speech) -->
<div aria-live="assertive">
  Error: Your session is about to expire in 30 seconds.
</div>

<!-- Role-based alternatives -->
<div role="status">
  5 new messages received.
</div>

<div role="alert">
  Form could not be submitted due to validation errors.
</div>

• aria-atomic="true|false": Whether the entire region should be announced as a whole when any part changes
• aria-relevant="additions|removals|text|all": What types of changes should be announced
• aria-busy="true|false": Indicates the element is being updated

1. Use HTML first: Always prefer native HTML elements when available
2. Maintain relationships: Ensure control elements reference the elements they control
3. Update ARIA states dynamically: Change aria-expanded, aria-selected, etc. when state changes
4. Test with assistive technologies: Verify your ARIA works as expected with screen readers
5. Keep it simple: Only add ARIA that provides necessary information

1. Redundant ARIA

<!-- Redundant: button already has role="button" implicitly -->
<button role="button">Click me</button>

<!-- Redundant: h1 already has implicit heading role -->
<h1 role="heading" aria-level="1">Page Title</h1>

2. Conflicting ARIA

<!-- Conflicting: changing the native semantics inappropriately -->
<h1 role="button">This is not a proper button</h1>

<!-- Conflicting: list item outside of a list -->
<div role="listitem">Item without a list parent</div>

3. Incomplete ARIA

<!-- Missing associated elements -->
<div role="tablist">
  <div role="tab">Tab 1</div> <!-- Missing aria-controls -->
</div>
<div>Tab 1 content</div> <!-- Missing role="tabpanel" -->

<!-- Missing keyboard support for interactive elements -->
<div role="button">Submit</div> <!-- No tabindex or event handlers -->

4. Missing Key Functionality

<!-- Role without keyboard support -->
<div role="button" onclick="submitForm()">Submit</div>
<!-- Missing tabindex and keyboard event handlers -->

<!-- Fix: Add keyboard support -->
<div role="button" 
     onclick="submitForm()" 
     onkeydown="handleKeydown(event)" 
     tabindex="0">
  Submit
</div>
<script>
  function handleKeydown(event) {
    // Handle Enter and Space keys
    if (event.key === 'Enter' || event.key === ' ') {
      event.preventDefault();
      submitForm();
    }
  }
</script>

<div class="dropdown">
  <button aria-haspopup="true" 
          aria-expanded="false" 
          aria-controls="dropdown-menu">
    Settings
    <span class="icon" aria-hidden="true">▼</span>
  </button>
  
  <ul id="dropdown-menu" 
      role="menu" 
      hidden>
    <li role="menuitem">
      <button>Profile</button>
    </li>
    <li role="menuitem">
      <button>Account</button>
    </li>
    <li role="menuitem">
      <button>Logout</button>
    </li>
  </ul>
</div>

<script>
  const dropdown = document.querySelector('.dropdown button');
  const menu = document.getElementById('dropdown-menu');
  
  dropdown.addEventListener('click', () => {
    const expanded = dropdown.getAttribute('aria-expanded') === 'true';
    dropdown.setAttribute('aria-expanded', !expanded);
    menu.hidden = expanded;
  });
  
  // Additional keyboard handling would be needed
</script>

<form>
  <div class="form-group">
    <label for="email">Email Address</label>
    <input type="email" 
           id="email" 
           aria-describedby="email-error" 
           aria-invalid="false">
    <div id="email-error" 
         class="error-message" 
         role="alert" 
         hidden></div>
  </div>
  
  <button type="submit">Submit</button>
</form>

<script>
  const emailInput = document.getElementById('email');
  const emailError = document.getElementById('email-error');
  
  emailInput.addEventListener('blur', () => {
    if (!isValidEmail(emailInput.value)) {
      emailInput.setAttribute('aria-invalid', 'true');
      emailError.textContent = 'Please enter a valid email address';
      emailError.hidden = false;
    } else {
      emailInput.setAttribute('aria-invalid', 'false');
      emailError.hidden = true;
    }
  });
  
  function isValidEmail(email) {
    // Email validation logic here
    return /\S+@\S+\.\S+/.test(email);
  }
</script>

<button onclick="loadData()">Load Data</button>

<div id="loading-indicator" role="status" aria-live="polite" hidden>
  Loading data, please wait...
</div>

<div id="results-container" aria-live="polite">
  <!-- Results will be inserted here -->
</div>

<script>
  function loadData() {
    const loadingIndicator = document.getElementById('loading-indicator');
    const resultsContainer = document.getElementById('results-container');
    
    // Show loading message
    loadingIndicator.hidden = false;
    
    // Simulate data loading
    setTimeout(() => {
      // Hide loading message
      loadingIndicator.hidden = true;
      
      // Update results
      resultsContainer.innerHTML = '<p>Data loaded successfully! 5 items found.</p>';
    }, 2000);
  }
</script>