HTML onwaiting Attribute

Introduction

The onwaiting attribute is an inline event handler that runs JavaScript when the waiting event fires on an audio or video element. It runs when playback pauses because the next frame is not available — the player has consumed its buffer and is waiting for more data to download. Use it to show a “Buffering…” spinner or message, then clear it on onplaying. This is different from onstalled (download stuck) and onpause (user paused). Prefer addEventListener("waiting", …) in production.

What You’ll Learn

Purpose of onwaiting Attribute

The primary purpose of onwaiting is to react when playback stops temporarily for buffering — so your page can show a loading indicator, disable seek controls, or reassure users that content is still loading rather than frozen.

The waiting event fires when the media element cannot keep playing because data has not arrived fast enough. When enough data buffers again, playing fires and playback resumes. Always pair onwaiting with onplaying to hide the buffering UI.

📝 Syntax

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

<video controls onwaiting="handleWaiting()">
  <source src="/video/count.mp4" type="video/mp4">
</video>

<script>
  media.onwaiting = handleWaiting;
  media.addEventListener("waiting", handleWaiting);
  media.addEventListener("playing", clearBufferingUI);
</script>

Syntax Rules

• Value is JavaScript executed when the waiting event fires.
• Valid on <audio> and <video> elements.
• Fires when playback stops because buffered data ran out.
• May fire multiple times during playback on slow connections.
• Also assignable as element.onwaiting in script.
• Modern alternative: addEventListener("waiting", handler).
• Pair with onplaying to clear buffering indicators.

💎 Values

The onwaiting attribute accepts a string of JavaScript code:

• onwaiting="handleWaiting()" — Call a named function.
• onwaiting="showBufferSpinner()" — Show buffering UI.
• JavaScript: video.onwaiting = () => { … } — property assignment.

function handleWaiting() {
  status.textContent = "Buffering…";
  status.setAttribute("aria-busy", "true");
}

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

Applicable Elements

onwaiting vs onstalled vs onplaying vs onpause

Examples Gallery

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

<video controls onwaiting="handleWaiting()">
  <source src="/video/count.mp4" type="video/mp4">
</video>
<p id="status" aria-live="polite"></p>

<script>
  function handleWaiting() {
    document.getElementById("status").textContent = "Buffering…";
  }
</script>

<script>
  document.getElementById("dynamicAudio").onwaiting = function () {
    log.textContent = "Audio is waiting for data.";
  };
</script>

media.addEventListener("waiting", function () {
  status.textContent = "Buffering…";
  status.setAttribute("aria-busy", "true");
});

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

♿ Accessibility

• Announce buffering — Use aria-live="polite" and aria-busy="true" on status text during waiting.
• Clear on resume — Remove aria-busy when playing fires.
• Do not rely on color alone — Pair spinner colors with text like “Buffering…”
• Keyboard access — Native controls remain usable during buffering.
• Avoid alert() — Blocking dialogs during buffering harm UX and accessibility.

💡 Best Practices