HTML onsuspend Attribute

Introduction

The onsuspend attribute is an inline event handler that runs JavaScript when the suspend event fires on an audio or video element. It runs when the browser intentionally pauses loading media data — often because enough bytes are buffered for current playback, or because preload limits how much is fetched upfront. This is not the same as the user pausing playback (onpause) or a network stall (onstalled). Use onsuspend to track loading state, log bandwidth-saving behavior, or pair with onprogress for buffer UX. Prefer addEventListener("suspend", …) in production.

What You’ll Learn

Purpose of onsuspend Attribute

The primary purpose of onsuspend is to react when the browser stops fetching more media data — so your page can update loading indicators, analytics, or debug logs. The suspend event is usually normal behavior: the user agent has buffered enough for now and pauses the download to save bandwidth.

It can also fire when preload="none" or preload="metadata" limits initial loading. Do not treat every suspend as a network error — pair with onstalled or onerror for problems.

📝 Syntax

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

<video controls onsuspend="handleSuspend()">
  <source src="/video/count.mp4" type="video/mp4">
</video>

<script>
  media.onsuspend = handleSuspend;
  media.addEventListener("suspend", handleSuspend);
</script>

Syntax Rules

• Value is JavaScript executed when the suspend event fires.
• Valid on <audio> and <video> elements.
• Fires when media data loading is intentionally suspended by the browser.
• Often fires multiple times during a single load/play session.
• Also assignable as element.onsuspend in script.
• Modern alternative: addEventListener("suspend", handler).
• Not the same as onpause (user pause) or onstalled (network stall).

💎 Values

The onsuspend attribute accepts a string of JavaScript code:

• onsuspend="handleSuspend()" — Call a named function.
• onsuspend="logLoadingState()" — Update a loading status label.
• JavaScript: video.onsuspend = () => { … } — property assignment.

function handleSuspend() {
  status.textContent = "Data loading suspended — buffered enough for now";
  status.classList.add("is-suspended");
}

media.addEventListener("suspend", handleSuspend);
media.addEventListener("progress", function () {
  status.textContent = "Loading media data…";
  status.classList.remove("is-suspended");
});

Applicable Elements

onsuspend vs onstalled vs onpause vs onwaiting

Examples Gallery

Inline video handler, dynamic audio assignment, and suspend + progress status pair.

<video controls onsuspend="handleSuspend()">
  <source src="/video/count.mp4" type="video/mp4">
</video>
<p id="status"></p>

<script>
  function handleSuspend() {
    document.getElementById("status").textContent =
      "Media data loading suspended";
  }
</script>

<script>
  document.getElementById("dynamicAudio").onsuspend = function () {
    log.textContent = "Data loading suspended by the browser.";
  };
</script>

media.addEventListener("progress", function () {
  status.textContent = "Loading media data…";
});

media.addEventListener("suspend", function () {
  status.textContent = "Loading suspended — enough buffered";
});

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

♿ Accessibility

• Do not alarm users on suspend — Suspend is usually normal; avoid error-style messaging unless paired with stalled or error.
• Loading state — Use aria-busy or aria-live="polite" only when playback is actually waiting (waiting event).
• Keep controls usable — Suspend does not disable native play/pause buttons.
• Captions — Suspend affects data fetch, not caption tracks already loaded.
• Avoid alert() — Use visible status text for loading feedback.

💡 Best Practices