CSS ::cue: improve caption contrast without editing the transcript

Last updated: 5 Oct 20265 min read

tutorial

The ::cue pseudo-element targets rendered WebVTT caption or subtitle cues for a media element. Only a restricted set of CSS properties applies to cue text. It does not create captions, correct timing, identify speakers, or guarantee that a third-party player will honor the stylesheet.

When to use it

A training clip includes an English captions track with speech and relevant sounds. The default cue rendering is hard to read over bright frames, so the player scope requests light text on a dark translucent background. Keep the underlying VTT content complete and provide a transcript route for someone who cannot use the video. Test captions over bright and dark footage, with native controls visible, at high zoom, in full screen, and on platforms with user caption preferences. The browser may prioritize a viewer's system settings, which is appropriate. Do not force an ornate typeface or tiny line-height to match branding. A caption should not obscure the only visual instruction in the frame; production work may need track positioning and video editing, beyond CSS. Verify the correct track language and that captions can be enabled by keyboard. If the track fails to load, paint cannot compensate for missing timed text.

.training-clip::cue { color: #fff; background-color: rgb(12 30 42 / 88%); font-family: sans-serif; }
@media (forced-colors: active) { .training-clip::cue { color: CanvasText; background-color: Canvas; } }

Cost and verification

The cue paint itself is small, but caption accessibility depends on the VTT file, language labels, sync, player support, and viewer settings. Test the actual target browsers instead of assuming every CSS declaration inside ::cue will apply; layout properties outside the allowed cue set may be ignored. A dark rectangle can improve contrast but may cover content if a cue is too long. Edit the caption text or cue breaks at the source when readability fails; do not shrink the font until the full sentence fits. CSS cannot add missing sound descriptions or replace a separate transcript. Keep user preferences in control of caption appearance where the platform exposes them.

Common Mistakes

Do not expect ::cue to generate captions or a transcript.
Do not assume every ordinary CSS property applies to cue text.
Do not override viewer preferences to preserve a brand treatment.

Connected lessons

Further rendering decisions

CSS :fullscreen: lay out media after the browser enters full screen

css

reference

web