HTML onprogress Attribute

Introduction

The onprogress attribute is an inline event handler for the progress event on audio or video elements. It runs periodically while the browser downloads and buffers media data — useful for showing a loading bar or “buffering…” message before playback can start smoothly. Read media.buffered and media.duration to estimate percent loaded. Pair with oncanplaythrough when loading finishes. Prefer addEventListener("progress", …) in production. Note: onprogress does not work reliably on <img> elements.

What You’ll Learn

Purpose of onprogress Attribute

The primary purpose of onprogress is to give users real-time feedback while media is being fetched — updating a progress bar, showing a spinner, or displaying “Loading 45%…” before the file is ready to play without interruption.

The progress event fires on the media element as the browser downloads data. Unlike a one-time event such as canplaythrough, progress can fire many times as more bytes arrive. Use the buffered TimeRanges API to measure how much is loaded.

📝 Syntax

Set onprogress on audio or video, or assign media.onprogress in JavaScript:

<audio controls preload="auto"
       onprogress="updateProgress(event)"
       oncanplaythrough="markReady()">
  <source src="/audio/count.mp3" type="audio/mpeg">
</audio>

<script>
  media.onprogress = updateProgress;
</script>

Syntax Rules

• Value is JavaScript executed when the progress event fires.
• Valid on <audio> and <video> elements.
• Use preload="auto" or preload="metadata" so loading starts before play.
• Read event.target.buffered to calculate loaded percentage.
• Pair with oncanplaythrough to hide the loader when done.
• Modern alternative: media.addEventListener("progress", handler).
• Does not work on <img> — use media elements instead.

💎 Values

The onprogress attribute accepts a string of JavaScript code:

• onprogress="updateProgress(event)" — Call a named function with the event.
• onprogress="status.textContent = 'Loading…'" — Inline statement.
• JavaScript: audio.onprogress = (event) => { … } — property assignment.

function updateProgress(event) {
  var media = event.target;
  if (!media.duration || media.buffered.length === 0) return;
  var end = media.buffered.end(media.buffered.length - 1);
  var pct = Math.round((end / media.duration) * 100);
  status.textContent = "Buffering… " + pct + "%";
}

audio.addEventListener("progress", updateProgress);

Applicable Elements

onprogress vs oncanplaythrough vs onwaiting

Examples Gallery

Inline audio handler, dynamic assignment, and a visual progress bar with addEventListener.

<audio controls preload="auto"
       onprogress="updateProgress(event)"
       oncanplaythrough="markReady()">
  <source src="/audio/count.mp3" type="audio/mpeg">
</audio>
<p id="status">Loading…</p>

<script>
  audio.onprogress = function (event) {
    var pct = bufferPercent(event.target);
    status.textContent = "Buffering… " + pct + "%";
  };
  audio.oncanplaythrough = markReady;
</script>

media.addEventListener("progress", function () {
  var pct = bufferPercent(media);
  bar.style.width = pct + "%";
  label.textContent = "Loading… " + pct + "%";
});

media.addEventListener("canplaythrough", function () {
  bar.style.width = "100%";
  label.textContent = "Ready to play";
});

♿ Accessibility

• Announce loading state — Put status text in an element with aria-live="polite" so screen readers hear progress updates.
• Do not rely on color alone — Pair the progress bar with a text percentage.
• Keep controls usable — Do not block native media controls while loading.
• Avoid rapid announcements — Throttle live-region updates if progress fires very often.
• Respect reduced motion — Skip animated spinners when prefers-reduced-motion is set.

💡 Best Practices