HTML onended Attribute

Introduction

The onended attribute is an inline event handler that runs JavaScript when the ended event fires. That happens on <audio> and <video> when playback reaches the end of the media naturally. Use it to show a replay button, play the next track in a playlist, display a “Thanks for watching” message, or log analytics. It does not fire when the user pauses mid-playback (that is onpause) or when media is reset (that is onemptied). With the loop attribute enabled, ended typically does not fire because playback restarts automatically.

What You’ll Learn

Purpose of onended Attribute

The primary purpose of onended is to react when media playback completes. You might reveal a replay button, advance to the next song, show end-screen credits, or trigger completion tracking. It is a one-time event at the natural end of the timeline — unlike ontimeupdate, which fires continuously during playback.

Pair onended with playlist logic in JavaScript: when one clip finishes, load and play the next. For single clips, update UI to invite the user to replay or navigate elsewhere.

📝 Syntax

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

<script>
  function handleMediaEnd() {
    console.log("Playback finished.");
  }
</script>

<audio controls onended="handleMediaEnd()">
  <source src="song.mp3" type="audio/mpeg">
</audio>

Syntax Rules

• Value is JavaScript code executed when the ended event fires.
• Applies to <audio> and <video> media elements.
• Fires when playback reaches the end — not on pause or seek.
• JavaScript: media.onended = function() { … }.
• Modern alternative: media.addEventListener("ended", handler).
• Usually skipped when loop is enabled (media restarts).

💎 Values

The onended attribute accepts a string of JavaScript code:

• onended="handleMediaEnd()" — Call a named function.
• onended="showReplay()" — Inline statement.
• JavaScript: video.onended = () => { … } assigns the handler.

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

video.addEventListener("ended", () => {
  document.getElementById("replay-btn").hidden = false;
});

document.getElementById("replay-btn").addEventListener("click", () => {
  video.currentTime = 0;
  video.play();
  document.getElementById("replay-btn").hidden = true;
});

Applicable Elements

onended vs onpause vs ontimeupdate

Examples Gallery

Inline onended on audio, addEventListener on video, and a simple replay pattern.

<script>
  function handleMediaEnd() {
    console.log("Media playback has ended!");
  }
</script>

<audio controls onended="handleMediaEnd()">
  <source src="song.mp3" type="audio/mpeg">
  Your browser does not support the audio element.
</audio>

<script>
  document.getElementById("dynamicAudio").addEventListener("ended", function () {
    console.log("Custom ended event triggered!");
  });

  // Or property form:
  document.getElementById("dynamicAudio").onended = function () { /* … */ };
</script>

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

video.addEventListener("ended", () => {
  replay.hidden = false;
});

replay.addEventListener("click", () => {
  video.currentTime = 0;
  video.play();
  replay.hidden = true;
});

♿ Accessibility

• Announce completion — Use a live region when playback ends if custom controls replace native ones.
• Make replay keyboard-accessible — Replay buttons need focus styles and Enter/Space support.
• Avoid alert() on ended — Update visible status or show an in-page end screen instead.
• Do not autoplay the next clip silently — Respect user preferences; offer a clear next action.
• Captions through the end — Ensure subtitle tracks display through the final frame.

💡 Best Practices