aria-busy — Indicating Loading or Updating Elements

In this tutorial, you will learn about aria. We cover key concepts, practical examples, and best practices to help you master this topic.

aria-busy indicates that an element is currently loading or updating, telling screen readers to wait before announcing changes until the element is no longer busy.

In this tutorial, you'll learn how to use aria-busy to manage live region timing in your ARIA implementations.

What You'll Learn

By the end of this lesson, you'll understand when to set aria-busy, how it interacts with live regions, how to clear it when loading completes, and how to test the behavior.

Why It Matters

Without aria-busy, screen readers may announce partially loaded content, giving users incorrect information. Setting aria-busy defers announcements until the update is complete.

Real-World Use

Durga Antivirus Pro sets aria-busy on scan result regions while scanning and removes it when results are ready, ensuring users hear the complete summary at once.

Busy State in Live Regions

flowchart LR
  A[Region starts loading] --> B[Set aria-busy='true']
  B --> C[Content updates progressively]
  C --> D[Loading complete]
  D --> E[Set aria-busy='false']
  E --> F[Screen reader announces final content]

How aria-busy Works

When aria-busy="true" is set on a live region, screen readers queue the changes but do not announce them until aria-busy is set to false:

<div aria-live="polite" aria-busy="true" id="results">
  <!-- Content being loaded -->
</div>

async function loadResults() {
  const region = document.getElementById('results');
  region.setAttribute('aria-busy', 'true');

  const data = await fetch('/api/scan-results');
  region.innerHTML = renderResults(data);

  // Now screen readers will announce the full content
  region.setAttribute('aria-busy', 'false');
}

When to Use aria-busy

Use aria-busy when:

• Content is loaded in multiple stages
• Data comes from multiple API calls
• Content should be announced as a complete unit
• Intermediate states would confuse users

function updateDashboard() {
  const dashboard = document.getElementById('dashboard');
  dashboard.setAttribute('aria-busy', 'true');

  updateStats();
  updateChart();
  updateTable();

  // All updates are batched into one announcement
  dashboard.setAttribute('aria-busy', 'false');
}

aria-busy Without Live Regions

aria-busy can also be used outside live regions to indicate loading state:

<div role="region" aria-busy="true" aria-label="Loading scan results">
  <p>Scanning files...</p>
</div>

When aria-busy transitions from true to false, screen readers can notify users that the content is now ready.

Common Mistakes

• Setting aria-busy but never clearing it: The live region will never announce its content.
• Using aria-busy on non-live regions expecting announcements: It only affects announcement timing within live regions.
• Skipping aria-busy for multi-step updates: Users hear partial content that changes multiple times.
• Setting aria-busy on the entire page: This would suppress all announcements.
• Not testing with screen readers: The timing of when content is announced varies between screen readers.

Practice and Challenge

1. What does aria-busy="true" do? Indicates an element is loading and defers live region announcements.

2. When do announcements happen on an aria-busy live region? When aria-busy is set back to false.

3. Should you always use aria-busy with live regions? Only when content loads in stages or needs to be announced as a complete unit.

4. What happens if you never set aria-busy to false? The live region will never announce its content.

5. Challenge: Create a component that loads two API endpoints and displays results. Use aria-busy to delay announcement until both endpoints return.

FAQ

Mini Project

Create a dashboard widget that loads data from two API calls. Use aria-busy to suppress announcements until both calls complete, then announce the full result.

What's Next

Continue to aria-current to learn how to indicate the current item in a set.