HTML oncuechange Attribute

Introduction

The oncuechange handler runs JavaScript when the cuechange event fires on a TextTrack. That happens when the set of active cues changes during <audio> or <video> playback—for example when a WebVTT caption line starts or ends. Use it to build custom caption displays, log subtitle timing, or sync UI with timed text. Attach the handler to textTrack.oncuechange or addEventListener("cuechange", …) on the track from media.textTracks. Set textTrack.mode to "hidden" or "showing" so cues activate.

What You’ll Learn

Purpose of oncuechange

The primary purpose of oncuechange is to run JavaScript when the active cues on a text track change. Cues are timed lines in a WebVTT file (captions, subtitles, or metadata). When playback reaches a cue start or end time, the browser fires cuechange on the TextTrack object.

Use it to build custom caption panels, highlight transcript lines, log subtitle timing, or sync UI with spoken content. The handler attaches to textTrack.oncuechange or textTrack.addEventListener("cuechange", …)—not as a standard inline HTML attribute on <track>.

📝 Syntax

Attach the handler on the TextTrack from media.textTracks:

<audio id="clip" controls>

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

  <track kind="captions" src="/audio/count.vtt" srclang="en" label="English">

</audio>



<script>

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

  const track = audio.textTracks[0];

  track.mode = "hidden";

  track.addEventListener("cuechange", handleCueChange);



  function handleCueChange() {

    const cues = track.activeCues;

    if (!cues || cues.length === 0) return;

    console.log(cues[0].text);

  }

</script>

Syntax Rules

• Handler runs when the set of active cues on a TextTrack changes.
• Attach to the TextTrack from audio.textTracks or video.textTracks.
• Set textTrack.mode to "hidden" or "showing" so cues become active.
• Read current lines from textTrack.activeCues inside the handler.
• Property form: textTrack.oncuechange = function() { … }.
• Preferred: textTrack.addEventListener("cuechange", handler).

💎 Values

oncuechange is an event-handler property on TextTrack, not a string attribute on HTML:

• track.oncuechange = handleCueChange — Assign a function reference.
• track.oncuechange = function() { … } — Inline function.
• track.addEventListener("cuechange", handleCueChange) — Preferred modern form.

const track = video.textTracks[0];

track.mode = "showing";

track.oncuechange = function () {

  const panel = document.getElementById("caption-panel");

  const cues = track.activeCues;

  panel.textContent = cues.length ? cues[0].text : "";

};

Applicable Elements

oncuechange vs timeupdate vs onloadedmetadata

Examples Gallery

addEventListener on TextTrack, the oncuechange property, and cuechange vs timeupdate.

<audio id="clip" controls>

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

  <track kind="captions" src="/audio/count.vtt" srclang="en">

</audio>



<script>

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

  audio.addEventListener("loadedmetadata", () => {

    const track = audio.textTracks[0];

    track.mode = "hidden";

    track.addEventListener("cuechange", () => {

      for (const cue of track.activeCues) {

        console.log("Active cue:", cue.text);

      }

    });

  });

</script>

const track = audio.textTracks[0];

track.mode = "showing";

track.oncuechange = function () {

  console.log("Cue change detected!");

  for (let cue of track.activeCues) {

    console.log("Active cue:", cue.text);

  }

};

audio.addEventListener("timeupdate", () => {

  // Fires frequently — good for progress bars

});



track.addEventListener("cuechange", () => {

  // Fires only when active cues change — good for captions

});

♿ Accessibility

• Provide captions for video and audio — Use <track kind="captions"> with WebVTT files so deaf and hard-of-hearing users can follow content.
• Do not rely on cuechange alone — Native mode="showing" or a custom accessible caption panel should display text visibly.
• Contrast and readability — Custom caption UI needs sufficient color contrast and readable font size.
• Keyboard and controls — Let users toggle captions via native media controls or an accessible button.
• Live regions for custom UI — If you mirror captions in a separate div, consider aria-live="polite" for screen reader updates.

💡 Best Practices