CSS ::cue() Pseudo-Element

CSS ::cue() Pseudo-Element

The ::cue() pseudo-element selects specific elements within WebVTT captions and subtitles displayed by an HTML <video> element. Unlike ::cue, which styles cue content generally, the functional ::cue() form accepts a selector to target particular portions of caption text, such as bold text, italic text, or named caption classes.

Syntax

video::cue(selector) {
  property: value;
}

The video selector identifies the HTML video element.

The ::cue() pseudo-element targets supported elements within the video's WebVTT cue content.

The selector argument identifies which cue elements should receive the CSS declarations.

For example:

video::cue(b) {
  color: #ffff00;
}

This rule requests yellow text for bold elements inside WebVTT captions.

Another example targets a WebVTT class:

video::cue(.highlight) {
  color: #00ffff;
}

This rule targets cue text marked with the highlight class in the WebVTT file.

Important: The selector argument operates on WebVTT cue content, not on ordinary HTML elements elsewhere in the webpage.

How It Works

WebVTT caption files contain timed text that the browser displays during video playback.

In addition to ordinary text, WebVTT supports certain inline markup elements for formatting portions of a cue.

The ::cue() pseudo-element allows CSS to select these marked portions independently of the surrounding caption text.

For example, consider this WebVTT cue:

00:00:01.000 --> 00:00:04.000
This is <b>important</b> information.

The word "important" is enclosed in WebVTT bold markup.

The following CSS targets that portion:

video::cue(b) {
  color: #ffff00;
  font-weight: bold;
}

The browser can display the word "important" in yellow while the surrounding caption text retains its normal appearance.

The cue's timing, text content, and synchronization are unchanged.

The functional selector only affects the presentation of matching cue content.

WebVTT Caption Markup

WebVTT supports a limited collection of inline elements for identifying and formatting caption text.

Common WebVTT cue elements include:

These elements are written inside a WebVTT file, not as separate HTML elements in the webpage.

For example:

WEBVTT

00:00:01.000 --> 00:00:04.000
Learn <b>CSS</b> with <i>practical examples</i>.

00:00:04.500 --> 00:00:08.000
This is <c.highlight>highlighted text</c>.

The first cue contains bold and italic portions.

The second cue contains text assigned to a WebVTT class named highlight.

These markers provide styling targets for ::cue().

Styling Bold and Italic Text

The ::cue() pseudo-element can target supported bold and italic elements within WebVTT captions.

Styling Bold Text

video::cue(b) {
  color: #ffff00;
  font-weight: bold;
}

This rule styles text enclosed in WebVTT <b> markup.

Styling Italic Text

video::cue(i) {
  color: #00ffff;
  font-style: italic;
}

This rule styles text enclosed in WebVTT <i> markup.

Styling Underlined Text

video::cue(u) {
  text-decoration: underline;
  color: #ffcc00;
}

This rule targets text enclosed in WebVTT <u> markup.

These selectors allow different portions of a caption to use different visual styles.

The styles only appear when the corresponding markup exists in the WebVTT cue.

Styling WebVTT Classes

WebVTT supports class annotations using the <c> element.

Classes allow specific portions of caption text to receive custom styling.

For example:

00:00:01.000 --> 00:00:04.000
This is <c.highlight>important information</c>.

The <c.highlight> markup assigns the class highlight to the enclosed text.

The following CSS targets that class:

video::cue(.highlight) {
  color: #ffff00;
  font-weight: bold;
}

The highlighted portion can appear in yellow and bold while the rest of the caption retains its general styling.

Multiple classes can also be assigned to a WebVTT class span.

00:00:01.000 --> 00:00:04.000
This is <c.highlight.important>special text</c>.

The text has both the highlight and important classes.

A selector such as video::cue(.important) can target the matching class in browsers that support the functional pseudo-element.

Note: WebVTT class markup uses a special syntax. The class name appears after a period in the opening <c> tag.

Styling Speaker Voices

WebVTT supports voice annotations that identify who is speaking.

Voice annotations can help distinguish speakers in caption files.

For example:

WEBVTT

00:00:01.000 --> 00:00:04.000
<v Instructor>Welcome to the CSS tutorial.</v>

00:00:04.500 --> 00:00:08.000
<v Student>What is a pseudo-element?</v>

The first cue identifies the speaker as Instructor.

The second cue identifies the speaker as Student.

Voice annotations can be selected using the WebVTT voice attribute.

video::cue(v[voice="Instructor"]) {
  color: #ffff00;
}
video::cue(v[voice="Student"]) {
  color: #00ffff;
}

These rules request different text colors for the two speakers.

The browser must support the relevant WebVTT selector syntax for the styling to take effect.

Speaker identification should remain understandable without relying entirely on color.

Example

The following example combines general caption styling with selective styling for bold text and WebVTT classes.

HTML:

<video controls width="600">
  <source src="css-tutorial.mp4" type="video/mp4">
  <track src="captions.vtt" kind="captions" srclang="en" label="English" default>
  Your browser does not support HTML video.
</video>

CSS:

video {
  display: block;
  max-width: 100%;
  height: auto;
}
video::cue {
  color: #fff;
  background-color: rgb(0 0 0 / 80%);
  font-family: Arial, sans-serif;
  font-size: 20px;
}
video::cue(b) {
  color: #ffff00;
  font-weight: bold;
}
video::cue(.highlight) {
  color: #00ffff;
  font-weight: bold;
}

WebVTT File - captions.vtt:

WEBVTT

00:00:01.000 --> 00:00:04.000
Welcome to the <b>CSS tutorial</b>.

00:00:04.500 --> 00:00:08.000
Today we are learning about <c.highlight>pseudo-elements</c>.

00:00:08.500 --> 00:00:12.000
CSS can style <b>selected portions</b> of captions.

The general video::cue rule requests white caption text with a dark background.

The video::cue(b) rule requests yellow text for the bold portions.

The video::cue(.highlight) rule requests cyan text for portions marked with the highlight class.

The caption timing and text content remain controlled by the WebVTT file.

Note: Replace css-tutorial.mp4 and captions.vtt with actual files. The example requires a valid video and a matching caption track to display the styled cues.

::cue vs. ::cue()

The two forms are related but serve different styling purposes.

::cue

The ::cue pseudo-element styles cue content generally.

video::cue {
  color: #fff;
  background-color: #000;
}

This rule requests white caption text with a black background.

::cue()

The ::cue() pseudo-element targets specific supported elements within cue content.

video::cue(b) {
  color: #ffff00;
}

This rule requests yellow text for bold portions of the caption.

Both forms can be used together.

The general rule establishes the default caption appearance, while functional selectors customize selected portions.

Supported Selectors and Properties

The ::cue() pseudo-element does not accept every selector or CSS property available for ordinary HTML content.

Its selector argument is restricted to supported WebVTT cue elements and their permitted selector forms.

Common examples include:

Commonly supported styling properties include:

• color - Changes text color.
• background-color - Changes the background behind cue text.
• font-family - Changes the requested font family.
• font-size - Changes the requested text size.
• font-style - Changes italic or normal styling.
• font-weight - Changes text weight.
• text-decoration - Applies supported text decoration.
• text-shadow - Adds a shadow to cue text.

CSS layout properties such as display, margin, padding, and position should not be relied upon for styling WebVTT cue text.

Support for individual selectors and declarations may differ between browsers.

WebVTT STYLE Blocks

WebVTT files can contain a STYLE block that defines caption styling directly within the text track.

The functional ::cue() selector can be used inside these blocks.

For example:

WEBVTT

STYLE
::cue {
  color: white;
  background-color: black;
}
::cue(.highlight) {
  color: yellow;
}

00:00:01.000 --> 00:00:04.000
Learn about <c.highlight>CSS pseudo-elements</c>.

The general ::cue rule establishes the caption appearance.

The ::cue(.highlight) rule styles the class-marked portion.

The STYLE block must appear before the first cue in the WebVTT file.

WebVTT style blocks are useful when caption styling belongs specifically to a particular text track.

Styles defined in the webpage and styles defined inside the WebVTT file can both affect the displayed captions, subject to the applicable cascade rules and browser support.

Limitations

The ::cue() pseudo-element has several important limitations.

• It targets supported WebVTT cue elements rather than arbitrary HTML content.
• It requires matching markup within the WebVTT caption file.
• It does not accept unrestricted CSS selectors.
• It supports only a limited collection of CSS properties.
• It does not change caption timing, cue text, or synchronization.
• It cannot style captions permanently embedded in a video image.
• Browser and operating system caption preferences may affect the final appearance.
• Browser support for specific selector forms may vary.

For example, the following selector should not be used to target ordinary paragraphs elsewhere on the webpage:

video::cue(p) {
  color: yellow;
}

WebVTT cue content does not use ordinary HTML paragraph elements as supported cue markup.

Use selectors that correspond to valid WebVTT cue elements and annotations.

Accessibility Considerations

Selective caption styling can help distinguish speakers, emphasize important information, and improve readability.

However, the styling should support the caption text rather than replace essential information.

Follow these accessibility practices:

• Provide accurate captions for spoken dialogue and meaningful sounds.
• Use sufficient contrast between caption text and its background.
• Avoid relying on color alone to identify speakers or important information.
• Keep emphasized text readable against different video scenes.
• Respect viewer-selected caption appearance preferences when supported.
• Test caption readability on smaller screens.
• Ensure the captions remain understandable when custom styling is unavailable.

For example, speaker names can be included in the caption text when identifying the speaker is important.

This ensures that speaker identification is not dependent on a particular text color.

The ::cue() pseudo-element changes presentation, not the underlying meaning or timing of the captions.

Browser Support

The ::cue() pseudo-element is available in modern browsers that support WebVTT cue styling, but support for specific selectors and styling properties can vary.

Some browsers may support general ::cue styling more consistently than the functional ::cue() form.

Browser-native caption preferences and operating system accessibility settings can also influence the displayed styles.

For current compatibility information, visit Can I Use? and search for CSS ::cue and WebVTT caption styling.

Also consult the browser compatibility information in the MDN reference for ::cue.

Test the functional selector forms in the browsers used by your audience before relying on them for essential visual distinctions.

Specifications

The ::cue() pseudo-element is defined in the WebVTT specification .

The HTML text track model and the <track> element are defined in the WHATWG HTML Living Standard .

These specifications describe WebVTT cue markup, permitted styling selectors, and the association of timed text tracks with HTML media elements.