ARIA Roles & Attributes

<!-- The Toggle Header --&gt;
<h3 id="billing-header">
    <button aria-expanded="false" 
            aria-controls="billing-panel"
            class="accordion-trigger">
        Billing Information
        <span class="icon" aria-hidden="true">â–¼</span>
    </button>
</h3>

<!-- The Content Panel --&gt;
<div id="billing-panel" 
     role="region" 
     aria-labelledby="billing-header" 
     hidden 
     class="accordion-panel">
    <p>Please enter your payment methods and invoice history here.</p>
</div>

<!-- 1. The Container --&gt;
<div role="tablist" aria-label="Entertainment Settings">
    <!-- 2. The Triggers --&gt;
    <button role="tab" 
            aria-selected="true" 
            aria-controls="panel-video" 
            id="tab-video">Video</button>
    <button role="tab" 
            aria-selected="false" 
            aria-controls="panel-audio" 
            id="tab-audio" 
            tabindex="-1">Audio</button>
</div>

<!-- 3. The Panels --&gt;
<div role="tabpanel" 
     id="panel-video" 
     aria-labelledby="tab-video">
    [Video settings content...]
</div>
<div role="tabpanel" 
     id="panel-audio" 
     aria-labelledby="tab-audio" 
     hidden>
    [Audio settings content...]
</div>

<button aria-label="Close dialog">
    <span aria-hidden="true">×</span>
</button>

<nav aria-label="Primary navigation">
    <!-- Navigation links --&gt;
</nav>

<!-- Use when: --&gt;
<!-- - Icon-only buttons --&gt;
<!-- - Multiple similar elements need distinction --&gt;
<!-- - Visual label isn't descriptive enough --&gt;

<!-- aria-labelledby: Links to element that labels this one --&gt;
<div id="dialog-title">Confirm Delete</div>
<div role="dialog" aria-labelledby="dialog-title">
    <p>Are you sure?</p>
    <button>Delete</button>
    <button>Cancel</button>
</div>

<!-- aria-describedby: Links to element that describes this one --&gt;
<input type="password" 
       aria-describedby="password-requirements">
<div id="password-requirements">
    Must be 8+ characters with numbers and letters
</div>

<!-- Hide decorative content from screen readers --&gt;
<button>
    Save
    <span aria-hidden="true">💾</span>
</button>

<!-- Hide duplicate content --&gt;
<div aria-hidden="true">← Back</div>
<a href="/back">Back</a>

<!-- ⚠️ Warning: Never use aria-hidden on focusable elements! --&gt;
<button aria-hidden="true">Click me</button> <!-- ❌ Bad! --&gt;

<button aria-expanded="false" aria-controls="menu">
    Menu
</button>

<div id="menu" hidden>
    <!-- Menu items --&gt;
</div>

<script>
button.addEventListener('click', () => {
    const expanded = button.getAttribute('aria-expanded') === 'true';
    button.setAttribute('aria-expanded', !expanded);
    menu.hidden = expanded;
});
</script>

<!-- Common with: dropdowns, accordions, collapsible sections --&gt;

<!-- Indicate current page in navigation --&gt;
<nav>
    <a href="/">Home</a>
    <a href="/about">About</a>
    <a href="/blog" aria-current="page">Blog</a>
    <a href="/contact">Contact</a>
</nav>

<!-- Values: page, step, location, date, time, true, false --&gt;

<label for="email">Email:</label>
<input type="email" 
       id="email" 
       aria-invalid="true"
       aria-describedby="email-error">
<span id="email-error" role="alert">
    Please enter a valid email address
</span>

<script>
input.addEventListener('blur', () => {
    if (!input.validity.valid) {
        input.setAttribute('aria-invalid', 'true');
    } else {
        input.setAttribute('aria-invalid', 'false');
    }
});
</script>

<!-- Native disabled: Not focusable, not submittable --&gt;
<button disabled>Save</button>

<!-- aria-disabled: Focusable but indicates disabled state --&gt;
<button aria-disabled="true">Save</button>

<script>
// Must handle disabled state manually
button.addEventListener('click', (e) => {
    if (button.getAttribute('aria-disabled') === 'true') {
        e.preventDefault();
        return;
    }
    // Handle click
});
</script>

<!-- Use aria-disabled when: --&gt;
<!-- - Need element to remain in tab order --&gt;
<!-- - Need to explain why it's disabled --&gt;

<div role="dialog" 
     aria-labelledby="dialog-title"
     aria-modal="true">
    
    <h2 id="dialog-title">Confirm Action</h2>
    <p>Are you sure you want to proceed?</p>
    
    <button>Confirm</button>
    <button>Cancel</button>
</div>

<!-- aria-modal="true" tells screen readers this is modal --&gt;
<!-- Focus should be trapped inside dialog --&gt;
<!-- Escape key should close dialog --&gt;

<!-- Automatically announced --&gt;
<div role="alert">
    <p>Your session will expire in 5 minutes</p>
</div>

<!-- Or with aria-live --&gt;
<div aria-live="assertive" aria-atomic="true">
    <p>Error: Form submission failed</p>
</div>

<div role="progressbar" 
     aria-valuenow="45" 
     aria-valuemin="0" 
     aria-valuemax="100"
     aria-label="Upload progress">
    <div style="width: 45%">45%</div>
</div>

<!-- Better: Use native progress element --&gt;
<progress value="45" max="100">45%</progress>

<div role="checkbox" 
     aria-checked="false" 
     tabindex="0"
     aria-labelledby="checkbox-label">
    <span aria-hidden="true">☐</span>
</div>
<span id="checkbox-label">Accept terms</span>

<script>
checkbox.addEventListener('click', () => {
    const checked = checkbox.getAttribute('aria-checked') === 'true';
    checkbox.setAttribute('aria-checked', !checked);
    checkbox.querySelector('span').textContent = !checked ? '☑' : '☐';
});

// Handle keyboard (Space/Enter)
checkbox.addEventListener('keydown', (e) => {
    if (e.key === ' ' || e.key === 'Enter') {
        e.preventDefault();
        checkbox.click();
    }
});
</script>

<!-- ✅ Much better: Use native checkbox! --&gt;
<input type="checkbox" id="terms">
<label for="terms">Accept terms</label>

// Setting accessible properties directly on the element
const myButton = document.querySelector('custom-element').shadowRoot.querySelector('button');
myButton.ariaLabel = "Global Search";
myButton.ariaExpanded = "false";