Video player

Media

Open in Storybook: Video player (opens in a new tab)

Overview

The video player is built on the native video tag, or audio for a sound with no picture, and on native form controls: buttons, two ranges and a select. The controls attribute is not used. Playback is driven through a ref, so every control can be named, styled and tested.

The captions are drawn outside the player, as ordinary text, so they zoom and wrap like any text and never cover the controls. The track is kept hidden: the browser loads it, fires its cues and draws nothing.

One DOM, three bars. The bar answers to the room the player has, in a container query: over the picture with every control, over the picture with fewer, or below the picture and wrapped. The thumbnail of a card is VideoThumbnail, a component of its own, because a card chooses it and the width of a page does not.

Informational video with sound never autoplays. autoplay, loop and muted belong only to decorative video and to clips with no sound.

Anatomy

Usage

Use cases

Functional elements where you can play, pause, seek, mute and open each design. Every video is cut from Sintel, an open movie.

• Audio-only content

  Podcast or audio guide without picture: same controls, no captions toggle. A transcript is required (1.2.1) and its button is right below the player.

  Sintel · The trailer, sound only

  0:00-0:520:00 / 0:51

  Read the transcript

  audio with no controls, the same div role="group", a transcript button

• Decorative hero, 5 s or more

  Muted, aria-hidden, not focusable. Autoplay allowed. A visible Pause control is required.

  Open movie

  Meet Sintel and her dragon

  Pause background

  video muted autoplay loop aria-hidden="true" tabindex="-1", button “Pause background video”

• Decorative hero · reduced motion

  prefers-reduced-motion: the video is replaced by a static image. No Pause needed.

  

  Open movie

  Meet Sintel and her dragon

  img alt="", no video, no button

• Decorative micro-loop, under 5 s

  Muted and hidden from AT. Pause not required. Hidden under reduced motion.

  A dragon in flight

  Small loop next to the title. No controls: it lasts under 5 seconds and is hidden from assistive tech.

  video muted autoplay loop aria-hidden="true", no controls

• Informational, dialogue + audio, 5 s or more

  No autoplay: the user starts it. Captions and a recommended transcript.

  0:00-0:530:00 / 0:52

  EnglishItaliano

  Read the transcript

  track kind="captions", button aria-pressed, select for the language, transcript button

• Informational, dialogue + audio, under 5 s

  Same rules even if short: no autoplay with sound, captions required.

  0:01-0:030:01 / 0:04

  EnglishItaliano

  I'm searching for someone.

  track kind="captions", no autoplay

• Meaningful sound, no dialogue

  Manual play. Captions describe the sounds; never label them “subtitles”.

  0:03-0:050:03 / 0:08

  [music]

  track kind="captions" with “[music]”, no autoplay

• Silent but meaningful, 5 s or more

  No sound, so no mute or captions. Transcript or audio description required, a button below.

  0:00-0:080:00 / 0:08

  Read the transcript

  track kind="descriptions", button aria-pressed “Audio description”, transcript button

• Silent but meaningful, under 5 s

  Muted autoplay allowed; Pause optional. Short description below; hidden under reduced motion.

  0:00-0:040:00 / 0:04

  A young woman reaches out her hand as a small dragon flies past.

  video muted autoplay, a p that says what it shows

• Complex visuals + audio

  No autoplay. Captions plus an audio description track (or extended transcript).

  0:13-0:400:13 / 0:52

  EnglishItaliano

  What brings you to the land of the gatekeepers?

  Extended transcript with visual descriptions

  track kind="captions" and track kind="descriptions", button aria-pressed “Audio description”

• Thumbnails in cards

  The Play button is its own control, not nested in the card link. Its accessible name carries the title and duration. Play opens the full player in a modal dialog, and the guide opens in a drawer.

  • PlayCC0:52

    Sintel, the trailer

    Read the guide
  • PlayCC0:04

    Sintel, searching for someone

    Read the guide
  • PlayCC0:08

    Sintel, a dragon in the sky

    Read the guide

  button aria-haspopup="dialog" aria-label="Play video: Sintel, the trailer, 52 seconds"

Props

Example

The player is as wide as its slot and answers to it. Give the slot the width, never the player.

import { VideoPlayer } from '@/components/VideoPlayer'

<VideoPlayer
  src="/sintel-trailer.mp4"
  label="Sintel, official trailer"
  languages={[
    { code: 'en', label: 'English', src: '/trailer-en.vtt' },
    { code: 'it', label: 'Italiano', src: '/trailer-it.vtt' },
  ]}
  transcript={{
    label: 'Read the transcript',
    title: 'Transcript: Sintel, official trailer',
    text: transcript,
  }}
/>

Specs

States

Tokens

Component tokens

Guidelines

Controls by scenario and context

Each row is one scenario. Each column shows the control bar that design gets. Bars are scaled-down copies of the real controls (the control button is the component itself). Desktop uses the Large bar, smaller viewports the Medium bar or the thumbnail, and zoom the reflow layout.

• Solid: required in that context, never dropped
• Dashed: optional, or only if there is room (otherwise in the expanded player)
• Transcript linkOutside the player, below it

Zoom 400% · 320 CSS px. At 200% text size the desktop bar stays and wraps.

• Decorative hero, 5 s or more

  Background video in the header

  Live example

  Reduced motion

  Desktop · 640 px and upSize=Large

  Pause

  Pause only. Video is muted and aria-hidden. Name: “Pause background video”.

  Smaller viewport · 400–639 pxSize=Medium · in cards: Thumbnail

  Pause

  Same Pause button. Never dropped: 2.2.2.

  Zoom 400% · 320 CSS pxReflow layout

  Pause

  Same button, 44×44 at 1×. After reflow it must not cover the heading. Reduced motion: static image, no button.

• Decorative micro-loop, under 5 s

  Small loop by a title

  Live example

  Desktop · 640 px and upSize=Large

  No controls

  Muted, aria-hidden, autoplay allowed. Under 5 s, so 2.2.2 needs no Pause.

  Smaller viewport · 400–639 pxSize=Medium · in cards: Thumbnail

  No controls

  Same.

  Zoom 400% · 320 CSS pxReflow layout

  No controls

  Same. Reduced motion: hidden or first frame only.

• Informational, dialogue + audio, 5 s or more

  Tutorial or interview

  Live example

  Desktop · 640 px and upSize=Large

  0:06 / 0:30EN

  Play/Pause · Seek · Time · Mute · Volume · Captions · Caption language · Full screen

  Transcript

  Every control. No autoplay. Captions outside the player. Transcript link below (recommended).

  Smaller viewport · 400–639 pxSize=Medium · in cards: Thumbnail

  0:06 / 0:30

  Play/Pause · Seek (if room) · Time (if room) · Mute · Captions · Expand

  Card → Thumbnail

  Medium: Play, Mute, Captions, Expand always. Seek and time only if room. In a card under 400 px: Thumbnail, Play opens the dialog.

  Zoom 400% · 320 CSS pxReflow layout

  0:06 / 0:30

  Play/Pause · Mute · Captions · Expand · Seek (if room) · Time (if room)

  320 CSS px: required buttons on row 1, seek on its own row. Volume and caption language go to full screen. Captions wrap below.

• Informational, dialogue + audio, under 5 s

  Short tagline with voice-over

  Live example

  Desktop · 640 px and upSize=Large

  0:06 / 0:30EN

  Play/Pause · Seek · Time · Mute · Volume · Captions · Caption language · Full screen

  Identical to the 5 s+ row. Being short removes nothing: captions still required.

  Smaller viewport · 400–639 pxSize=Medium · in cards: Thumbnail

  0:06 / 0:30

  Play/Pause · Seek (if room) · Time (if room) · Mute · Captions · Expand

  Identical to the 5 s+ row.

  Zoom 400% · 320 CSS pxReflow layout

  0:06 / 0:30

  Play/Pause · Mute · Captions · Expand · Seek (if room) · Time (if room)

  Identical to the 5 s+ row.

• Informational, meaningful sound, no dialogue

  Coffee machine hissing demo

  Live example

  Desktop · 640 px and upSize=Large

  0:06 / 0:30

  Play/Pause · Seek · Time · Mute · Volume · Captions · Full screen

  Captions describe sounds: [steam hissing]. Caption language only if the sound captions are translated.

  Smaller viewport · 400–639 pxSize=Medium · in cards: Thumbnail

  0:06 / 0:30

  Play/Pause · Seek (if room) · Time (if room) · Mute · Captions · Expand

  Play, Mute, Captions, Expand always.

  Zoom 400% · 320 CSS pxReflow layout

  0:06 / 0:30

  Play/Pause · Mute · Captions · Expand · Seek (if room) · Time (if room)

  Same wrap as dialogue. Sound captions stay readable below.

• Informational, silent but meaningful, 5 s or more

  Product shown visually, no sound

  Live example

  Desktop · 640 px and upSize=Large

  0:06 / 0:30

  Play/Pause · Seek · Time · Audio description · Full screen

  Transcript

  No audio track, so no Mute, Volume or Captions. AD toggle if there is an AD track; transcript always.

  Smaller viewport · 400–639 pxSize=Medium · in cards: Thumbnail

  0:06 / 0:30

  Play/Pause · Seek (if room) · Time (if room) · Audio description · Expand

  Transcript

  Play, AD, Expand always. Transcript stays below the player.

  Zoom 400% · 320 CSS pxReflow layout

  0:06 / 0:30

  Play/Pause · Audio description · Expand · Seek (if room) · Time (if room)

  Transcript

  Required buttons on row 1. Transcript reflows below.

• Informational, silent but meaningful, under 5 s

  Short animation showing a feature

  Live example

  Desktop · 640 px and upSize=Large

  Pause (optional)

  Description

  Muted autoplay allowed; Pause optional. Short text description next to it.

  Smaller viewport · 400–639 pxSize=Medium · in cards: Thumbnail

  Pause (optional)

  Description

  Same. If Pause is shown it keeps 44×44.

  Zoom 400% · 320 CSS pxReflow layout

  Pause (optional)

  Description

  Same. Reduced motion: static frame plus the description.

• Informational, complex visuals + audio

  Product video with dense visuals and narration

  Live example

  Desktop · 640 px and upSize=Large

  0:06 / 0:30EN

  Play/Pause · Seek · Time · Mute · Volume · Captions · Caption language · Audio description · Full screen

  Extended transcript

  Everything in the dialogue row plus the AD toggle (or an extended transcript).

  Smaller viewport · 400–639 pxSize=Medium · in cards: Thumbnail

  0:06 / 0:30

  Play/Pause · Seek (if room) · Time (if room) · Mute · Captions · Audio description · Expand

  Play, Mute, Captions, AD, Expand always. Seek and time only if room.

  Zoom 400% · 320 CSS pxReflow layout

  0:06 / 0:30

  Play/Pause · Mute · Captions · Audio description · Expand · Seek (if room) · Time (if room)

  Five required buttons on row 1, seek on row 2.

The component differs from the matrix in two places: from 336px, not 400px, its Medium bar is over the picture, so the player of a card or a phone keeps its controls with the video; and at 320 CSS px it wraps Volume and Caption language into the bar, as the reflow design draws it, instead of moving them to full screen.

Content

Behavior

Accessibility

Keyboard

Every control is native, so no key is handled by script except the seek arrows, which keep a fine step for a smooth thumb and jump a whole second. Seeking by keyboard means no dragging is needed.

Roles and properties

The silent seek slider

Two values do two jobs. The clock and the fill follow the video on every frame. The value of the slider is what a screen reader reads, and it must not follow the video, or the position would be read all the time. While a keyboard has the slider and the video plays, its value is held; it changes on focus and on a seek.

Zoom and text size

Announcements

A native control says its own name, role and value, so most of the player needs no announcement. What changes without a control being touched is said once with ariaNotify() from the player, never through a live region. The method puts nothing in the DOM: where a browser does not have it nothing is said, and the same words are on the page as text.

The rules of ariaNotify(), as the system uses it.

• One call for each event, after the DOM and the focus have changed.
• Called on the player: an element that is in the accessibility tree and stays.
• Priority normal. high is for what interrupts, like an error.
• The voice follows the lang of the element it is called on.
• Feature-detected: where the method is missing nothing is said, and no live region takes its place.
• Never role="status", role="alert" or aria-live.

if ('ariaNotify' in Element.prototype) {
  player.ariaNotify(cue.text, { priority: 'normal' })
}

WCAG criteria

Every criterion the player answers to, once, with its level and where the player meets it. The other sections say what the player does, not which criterion it is.

Related

• Video control button (opens in a new tab)

References

This section is still in progress.