CSS ::cue Pseudo-Element

Style Captions and Subtitles in HTML Videos

CSS ::cue Pseudo-Element

The ::cue pseudo-element styles captions and subtitles displayed by an HTML <video> element using WebVTT text tracks. It allows developers to customize the appearance of caption text, including its color, font, background, and text shadow, without modifying the caption file itself.

Syntax

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

The video selector identifies an HTML video element.

The ::cue pseudo-element targets the WebVTT cue text displayed by the video.

The color property controls the caption text color.

The background-color property controls the background behind the caption text.

For example:

video::cue {
  color: yellow;
  font-size: 20px;
}

This rule requests yellow caption text with a font size of 20 pixels.

Note: The ::cue pseudo-element applies to supported WebVTT text track cues. It does not style captions permanently embedded in a video image.

How It Works

HTML videos can display timed text tracks containing captions, subtitles, and other text information.

These tracks are commonly supplied using the Web Video Text Tracks format, known as WebVTT.

The browser reads the WebVTT file and displays the appropriate text at specified times during video playback.

The ::cue pseudo-element allows CSS to style the displayed cue text.

For example:

video::cue {
  color: #fff;
  background-color: rgb(0 0 0 / 80%);
  text-shadow: 1px 1px 2px #000;
}

This rule requests white caption text with a dark, semi-transparent background and a subtle text shadow.

The browser continues to manage caption timing, placement, and synchronization with the video.

CSS changes the presentation of the captions without changing their text or timestamps.

The final appearance may also be affected by browser behavior and the viewer's caption preferences.

Understanding WebVTT Captions

WebVTT is a text-based format used to associate timed text with video and audio content.

A WebVTT file typically uses the .vtt extension and begins with the WEBVTT header.

Each cue contains a start time, an end time, and the text to display.

For example, a file named captions.vtt might contain:

WEBVTT

00:00:01.000 --> 00:00:04.000
Welcome to this CSS tutorial.

00:00:04.500 --> 00:00:08.000
Today we are learning about pseudo-elements.

00:00:08.500 --> 00:00:12.000
The ::cue pseudo-element styles video captions.

The first cue appears from one second to four seconds into the video.

The second cue appears from 4.5 seconds to eight seconds.

The third cue appears from 8.5 seconds to 12 seconds.

The browser displays each cue at the appropriate time when the text track is enabled.

A WebVTT file can also contain cue identifiers, positioning settings, and supported inline text markup.

Important: The WEBVTT header and cue timestamps must follow the WebVTT format. The arrow between timestamps consists of two hyphens followed by a greater-than sign.

Styling Captions

The ::cue pseudo-element supports several CSS properties for controlling caption appearance.

Changing Text Color

video::cue {
  color: #ffff00;
}

This rule requests yellow caption text.

Changing Font Size

video::cue {
  font-size: 22px;
}

This rule requests a caption font size of 22 pixels.

Changing Font Family

video::cue {
  font-family: Arial, sans-serif;
}

This rule requests Arial as the caption font, with a generic sans-serif fallback.

Changing Font Weight

video::cue {
  font-weight: bold;
}

This rule requests bold caption text.

These properties can be combined to create a consistent caption appearance.

However, browsers and operating systems may apply viewer-selected caption preferences that affect the final rendering.

Supported CSS Properties

The ::cue pseudo-element supports a restricted set of CSS properties rather than every property available to ordinary HTML elements.

Commonly supported property groups include:

  • Color - color.
  • Background - background and related background properties.
  • Font - font-family, font-size, font-style, font-weight, and related font properties.
  • Text decoration - text-decoration and related text decoration properties.
  • Text effects - text-shadow.
  • Text layout - Selected properties such as line-height and white-space.
  • Visibility - visibility.
  • Opacity - opacity.

For example:

video::cue {
  color: #fff;
  background-color: rgb(0 0 0 / 75%);
  font-family: Arial, sans-serif;
  font-size: 20px;
  font-weight: bold;
  text-shadow: 1px 1px 2px #000;
}

Properties such as margin, padding, border, and position should not be relied upon for styling cue text.

Caption placement is primarily controlled through WebVTT cue settings and browser rendering behavior.

Individual CSS properties may also have browser-specific limitations when applied to cues.

Example

The following example connects an HTML video element to a WebVTT caption file and styles the displayed captions using ::cue.

HTML:

<video controls width="600">
  <source src="tutorial-video.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;
  font-weight: bold;
  text-shadow: 1px 1px 2px #000;
}

WebVTT File - captions.vtt:

WEBVTT

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

00:00:04.500 --> 00:00:08.000
These captions are styled with ::cue.

00:00:08.500 --> 00:00:12.000
CSS controls their visual appearance.

The <video> element provides the video playback interface.

The <source> element identifies the video file.

The <track> element connects the video to the WebVTT caption file.

The kind="captions" attribute identifies the track as captions.

The srclang="en" attribute identifies the track language as English.

The default attribute indicates that the track should be enabled by default when appropriate.

When the captions are displayed, the ::cue rule requests white text with a dark background and a subtle shadow.

Note: Replace tutorial-video.mp4 and captions.vtt with actual files. The example requires a valid video and a matching WebVTT caption track to demonstrate the result.

Backgrounds and Text Shadows

Caption backgrounds and text shadows can improve readability when video scenes contain changing colors or complex imagery.

Semi-Transparent Background

video::cue {
  color: #fff;
  background-color: rgb(0 0 0 / 75%);
}

The semi-transparent black background helps separate the caption text from the video image.

Text Shadow

video::cue {
  color: #fff;
  text-shadow: 1px 1px 3px #000;
}

The text shadow creates a dark edge around the caption text, making it easier to distinguish from bright backgrounds.

Combining Both Effects

video::cue {
  color: #fff;
  background-color: rgb(0 0 0 / 70%);
  text-shadow: 1px 1px 2px #000;
}

Using both techniques can provide a consistent appearance across different video scenes.

Avoid decorative effects that make captions difficult to read or interfere with viewer preferences.

::cue vs. ::cue()

CSS provides two related forms for targeting WebVTT caption content.

::cue

The ::cue pseudo-element targets the cue content generally.

video::cue {
  color: #fff;
}

This rule applies to supported cue text displayed by the selected video.

::cue()

The functional ::cue() pseudo-element accepts a selector that can target specific elements within WebVTT cue content.

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

This rule targets supported bold elements within the WebVTT cue text.

For example, a WebVTT cue could contain:

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

The word "important" can receive different styling from the surrounding cue text.

The functional form provides more selective styling but is restricted to selectors supported for WebVTT cue content.

WebVTT STYLE Blocks

WebVTT files can also contain CSS styling rules inside a STYLE block.

This allows caption styling information to be included directly in the WebVTT file rather than only in the webpage's stylesheet.

For example:

WEBVTT

STYLE
::cue {
  color: yellow;
  background-color: black;
}

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

The STYLE block appears before the first cue.

The ::cue selector inside the block styles cue text within that WebVTT file.

The STYLE block must follow WebVTT syntax rules and cannot be inserted arbitrarily between cue lines.

Webpage CSS and WebVTT style blocks can both affect caption appearance, subject to the applicable cascade rules and browser support.

Keeping styling in the webpage is useful when several videos should share a consistent appearance.

Keeping styling in the WebVTT file can be useful when caption formatting is specific to one text track.

Limitations

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

  • It applies to supported WebVTT cue content rather than text permanently embedded in a video image.
  • It supports only a restricted set of CSS properties.
  • It does not change cue timing or synchronization.
  • It does not replace the need for a valid WebVTT text track.
  • It cannot be used to position captions freely with ordinary CSS positioning properties.
  • Browser and operating system caption preferences may affect the final appearance.
  • Rendering differences may occur between browsers and video playback environments.

For example, the following rule should not be relied upon to position captions at the top of a video:

video::cue {
  position: absolute;
  top: 0;
}

The position and top properties are not part of the normal supported styling set for WebVTT cue text.

Use WebVTT cue settings when caption positioning is required.

For example, WebVTT supports settings such as line, position, size, and align for controlling cue placement.

Accessibility Considerations

Captions and subtitles make video content more accessible to users who cannot hear or understand the audio.

When styling WebVTT captions, follow these accessibility practices:

  • Provide accurate captions for meaningful spoken content and relevant sounds.
  • Use sufficient contrast between caption text and the video background.
  • Choose readable fonts and appropriate text sizes.
  • Avoid excessive text shadows, animations, or decorative effects.
  • Allow users to enable or disable caption tracks through the video interface.
  • Respect user-selected caption appearance preferences when supported.
  • Test captions across different screen sizes and video scenes.

The ::cue pseudo-element changes the appearance of captions but does not create caption text or improve the accuracy of an existing caption file.

Captions should remain understandable even when custom CSS styling is unavailable.

For accessibility, prioritize readable text and accurate timing over decorative presentation.

Browser Support

The ::cue pseudo-element is supported in modern browsers that implement WebVTT caption styling, including Chrome, Edge, Firefox, and Safari, although styling capabilities can differ.

Support for particular CSS properties and more selective cue styling may vary between browsers.

Browser-native caption settings and operating system accessibility preferences may override or influence author-defined styles.

For current compatibility information, visit Can I Use? .

Test caption appearance in the browsers and devices used by your audience, especially when using backgrounds, text shadows, or custom fonts.

Specifications

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

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

These specifications describe how timed text tracks are associated with media elements and how CSS can style their displayed cue content.

See Also:
CSS ::cue() Pseudo-Element
CSS color Property
CSS background-color Property
CSS text-shadow Property
CSS font-size Property
HTML <video> Element
HTML <track> Element.

References:
MDN - ::cue
WebVTT Specification - ::cue
WHATWG HTML Living Standard - Track Element .

« Previous CSS Home Next »