Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / HTML

oncuechange — handle changes to active text-track cues

The oncuechange attribute specifies code to run for cuechange events when timed text-track cues become active or stop being active. A JavaScript property with the same name is also available on TextTrack objects.

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

Syntax

oncuechange="JavaScript statements"
trackElement.oncuechange = handler;
textTrack.oncuechange = handler;

oncuechange is a global event-handler attribute for cuechange. Its value contains JavaScript statements, not a file URL. A typical target is a track element inside video or audio; global availability does not mean the browser generates this event on every element.

The event indicates that one or more text-track cues have become active or stopped being active. The browser dispatches it to the TextTrack object and its corresponding track element, if one exists. It is not a notification that a subtitle file has finished downloading.

In an element handler, read this.track.activeCues to obtain the currently active cues; in a TextTrack handler, use this.activeCues. Account for null, especially when mode is "disabled". The "hidden" mode allows active cues to be tracked without displaying subtitles.

Assigning a function to oncuechange replaces the previous handler in that property; addEventListener("cuechange", handler) registers independent listeners. A CSP policy can block attribute-based code. The example deliberately dispatches a synthetic event: it checks attribute handling without media files but does not activate any track cues.

Examples

<!doctype html>
<meta charset="utf-8">
<title>oncuechange</title>
<video>
  <track id="captions" kind="captions" srclang="en" src="data:text/vtt,WEBVTT%0A%0A"
    oncuechange="document.getElementById('result').textContent = event.type + ': ' + this.kind">
</video>
<output id="result"></output>
<script>
  const trackElement = document.getElementById('captions');
  trackElement.dispatchEvent(new Event('cuechange'));
</script>

Result

cuechange: captions

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