HTML oncanplay Attribute

Introduction

The oncanplay attribute is an inline event handler that runs JavaScript when the canplay event fires. That happens on <audio> and <video> when the browser has buffered enough data that playback can start. Use it to hide loading spinners, enable custom play buttons, or log readiness. It does not mean the entire file is downloaded—only that playback can begin. For uninterrupted playback through the end, see oncanplaythrough.

What You’ll Learn

Purpose of oncanplay Attribute

The primary purpose of oncanplay is to react when media becomes ready to start. You might hide a “Loading…” overlay, enable a custom play button, start autoplay (where allowed), or sync UI with buffer state. The event is part of the media loading lifecycle alongside loadedmetadata, loadeddata, and canplaythrough.

The old reference used alert() in demos—avoid that in real apps. Status text or UI updates are clearer. Also note: canplay can fire multiple times if the user seeks or network conditions cause re-buffering.

📝 Syntax

Set oncanplay on audio or video, or assign element.oncanplay:

<script>

  function handleCanPlay() {

    console.log("Media can start playing.");

  }

</script>



<audio controls oncanplay="handleCanPlay()">

  <source src="song.mp3" type="audio/mpeg">

</audio>

Syntax Rules

• Value is JavaScript code executed when the canplay event fires.
• Applies to <audio> and <video> media elements.
• Fires when enough data is buffered to begin playback.
• JavaScript: media.oncanplay = function() { … }.
• Modern alternative: media.addEventListener("canplay", handler).
• May fire again after seeking or re-buffering.

💎 Values

The oncanplay attribute accepts a string of JavaScript code:

• oncanplay="handleCanPlay()" — Call a named function.
• oncanplay="hideLoader()" — Inline statement.
• JavaScript: video.oncanplay = () => { … } assigns the handler.

const video = document.getElementById("clip");

video.addEventListener("canplay", () => {

  document.getElementById("loader").hidden = true;

});

video.addEventListener("waiting", () => {

  document.getElementById("loader").hidden = false;

});

Applicable Elements

oncanplay vs oncanplaythrough vs onloadeddata

Examples Gallery

Inline oncanplay on audio, addEventListener on video, and media load event order.

<audio controls oncanplay="handleCanPlay()">

  <source src="song.mp3" type="audio/mpeg">

</audio>



<script>

  function handleCanPlay() {

    console.log("Media can start playing.");

  }

</script>

<script>

  document.getElementById("clip").addEventListener("canplay", function () {

    console.log("Video ready to play.");

  });



  // Or property form:

  document.getElementById("clip").oncanplay = function () { /* … */ };

</script>

audio.addEventListener("loadedmetadata", () => { /* duration known */ });

audio.addEventListener("loadeddata", () => { /* first frame */ });

audio.addEventListener("canplay", () => { /* can start */ });

audio.addEventListener("canplaythrough", () => { /* can play through */ });

♿ Accessibility

• Provide captions and transcripts — Media events do not replace accessible alternatives for audio and video content.
• Do not autoplay with sound — Respect user preferences; use canplay to enable controls, not surprise playback.
• Avoid alert() on canplay — Update visible status or hide loaders instead of blocking dialogs.
• Keyboard controls — Native controls attribute supports keyboard users; custom players need full keyboard support.
• Loading state — Announce buffer readiness to assistive tech with live regions if you hide native controls.

💡 Best Practices