1. Display
  2. Captions

Display

Captions

This component is used to render and display captions/subtitles.

Usage

The <media-captions> component renders and displays captions/subtitles. It will be rendered as an overlay when the player viewType is video, and as a simple captions box when the type is audio.

          
        

The captions component also be placed inside the <media-outlet> if the controls are outside of the video container:

          
        

Notes

  • The Text Tracks guide covers how to add, remove, and manage text tracks.
  • The player will dynamically switch to native captions when custom captions cannot be displayed (e.g., iOS Safari on iPhone).
  • Rendering is handled by the vidstack/media-captions library, see the repo for more information.
  • See the motivation section for why native captions should be avoided.
  • Refer to the formats section for positioning regions and cues. Also see the VTT and ASS specs.

Styling

You can style cues, voices, timed cues (past/future), and regions like so:

        media-captions {
}

media-captions [part='cue'] {
}

media-captions [part='cue'][data-id='...'] {
}

media-captions [part='voice'] {
}

media-captions [part='voice'][title='Joe'] {
}

media-captions [part='timed'] {
}

media-captions [part='timed'][data-past] {
}

media-captions [part='timed'][data-future] {
}

media-captions [part='region'] {
}

media-captions [part='region'][data-active] {
}

media-captions [part='region'][data-scroll='up'] {
}

      

CSS Variables

The following snippet contains a complete list of CSS variables and their default values. Any of the variables can be set to adjust the default caption styles:

css
        media-player {
  --media-captions-padding: 1%;

  --media-cue-display-bg: unset;
  --media-cue-display-border-radius: unset;
  --media-cue-display-padding: unset;

  --media-cue-font-size: calc(var(--overlay-height) / 100 * 5);
  --media-cue-line-height: calc(var(--media-cue-font-size) * 1.2);
  --media-cue-color: white;
  --media-cue-bg: rgba(0, 0, 0, 0.8);
  --media-cue-border-radius: 2px;
  --media-cue-box-shadow: unset;
  --media-cue-backdrop: blur(8px);
  --media-cue-padding-x: calc(var(--media-cue-font-size) * 0.6);
  --media-cue-padding-y: calc(var(--media-cue-font-size) * 0.4);
}

      

Avoiding Controls

        media-player:not([data-user-idle]) media-captions {
  /* Adjust 80px according to the height of your controls. */
  bottom: 80px;
  transition: bottom 0.3s;
}

      

Or, with Tailwind like so:

          
        

Component API

Props

Name Type

textDir

'ltr' | 'rtl'

Events

Name Type
Name Description
Name Type
Name Description

Instance Props

Name Type

Instance Methods

Name Type