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.