HTML onstalled Attribute

Introduction

The onstalled attribute is an inline event handler that runs JavaScript when the stalled event fires on an audio or video element. It runs when the browser is trying to fetch media data but data is not arriving for an unexpectedly long time — often due to a slow or interrupted network connection during download or buffering. Use it to show a “connection problem” message, offer a retry button, or log analytics. Pair with onwaiting and onplaying for full buffering UX. Prefer addEventListener("stalled", …) in production.

What You’ll Learn

Purpose of onstalled Attribute

The primary purpose of onstalled is to react when media data download stalls — so your page can inform the user, suggest checking their connection, or attempt recovery instead of leaving them with a frozen player and no explanation.

The stalled event fires on the media element when the user agent is actively trying to fetch data but none is forthcoming. It is related to network buffering issues, not the same as error (fatal load failure) or ended (playback finished).

📝 Syntax

Set onstalled on <audio> or <video>, or assign element.onstalled in JavaScript:

<audio controls onstalled="handleStalled()">
  <source src="/audio/count.mp3" type="audio/mpeg">
</audio>

<script>
  media.onstalled = handleStalled;
  media.addEventListener("stalled", handleStalled);
</script>

Syntax Rules

• Value is JavaScript executed when the stalled event fires.
• Valid on <audio> and <video> elements.
• Fires when media data fetch stalls — typically network-related.
• May fire multiple times during a single load on poor connections.
• Also assignable as element.onstalled in script.
• Modern alternative: addEventListener("stalled", handler).
• Use onerror for unrecoverable load failures.

💎 Values

The onstalled attribute accepts a string of JavaScript code:

• onstalled="handleStalled()" — Call a named function.
• onstalled="showRetryMessage()" — Show connection help text.
• JavaScript: audio.onstalled = () => { … } — property assignment.

function handleStalled() {
  status.textContent = "Download stalled — check your connection";
  status.classList.add("is-stalled");
}

media.addEventListener("stalled", handleStalled);
media.addEventListener("playing", function () {
  status.textContent = "Playing";
  status.classList.remove("is-stalled");
});

Applicable Elements

onstalled vs onwaiting vs onprogress vs onerror

Examples Gallery

Inline audio handler, dynamic assignment, and stalled + playing status pair for buffering UX.

<audio controls onstalled="handleStalled()">
  <source src="/audio/count.mp3" type="audio/mpeg">
</audio>
<p id="status"></p>

<script>
  function handleStalled() {
    document.getElementById("status").textContent =
      "Audio loading has stalled!";
  }
</script>

<script>
  document.getElementById("dynamicAudio").onstalled = function () {
    log.textContent = "Media download stalled. Please try again.";
  };
</script>

media.addEventListener("stalled", function () {
  status.textContent = "Download stalled";
  status.setAttribute("aria-busy", "true");
});

media.addEventListener("playing", function () {
  status.textContent = "Playing";
  status.removeAttribute("aria-busy");
});

♿ Accessibility

• Announce stalls — Use aria-live="polite" on status text when download stalls.
• Offer retry — Provide a visible button to reload media, not only a console message.
• Do not rely on color alone — Pair warning colors with clear text like “Connection problem.”
• Keyboard access — Ensure native controls remain usable during stalls.
• Captions — If video stalls, do not hide existing captions without reason.

💡 Best Practices