Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / HTML

onstalled — handling stalled media downloads

The onstalled attribute specifies code to run for the stalled event, when the browser is trying to fetch media data but data is not arriving. This concerns downloading, not necessarily an interruption of playback.

Version: WHATWG HTML Living Standard; index snapshot date recorded separately

Syntax

HTML: onstalled="JavaScript statements"
JavaScript: media.onstalled = handler;
Alternative: media.addEventListener("stalled", handler);

onstalled is an event handler content attribute for stalled. It is available as a global HTML attribute, but the browser naturally dispatches this event to the media elements audio and video. Its value contains JavaScript statements, not a resource address or a Boolean value.

The event occurs when an element is actively trying to obtain media data but receives none for the media stall timeout. It does not automatically mean an error or interrupted playback: buffered data may allow playback to continue. waiting concerns playback waiting for data, whereas suspend indicates that the browser has suspended fetching.

In HTML, use onstalled="..."; in JavaScript, assign a function to media.onstalled. Assignment replaces the previous handler in that slot. The alternative media.addEventListener("stalled", handler) registers independent listeners. Do not insert untrusted text into attribute code; Content Security Policy can block inline handlers.

The example dispatches a synthetic event to check the attribute wiring deterministically. It downloads no file and does not simulate actual network or buffer state. The expected paragraph text is stalled.

Examples

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>onstalled demonstration</title>
<audio id="media" onstalled="document.getElementById('status').textContent = event.type"></audio>
<p id="status">pending</p>
<script>
  const media = document.getElementById('media');
  media.dispatchEvent(new Event('stalled'));
</script>
</html>

Result

stalled

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources