Video is used for media layout.
Captions are intended for deaf and hard-of-hearing audiences. Captions are usually in the same language as the audio. Please, read the differences between captions and subtitles.
Read more about adding captions to video.
The following example uses an excerpt from the Sintel open movie, created by the Blender Foundation.
Video requires several accessibility labels for each video control:
If the video contain captions, it also requires
Autoplay and error detection
Autoplay or automatically starting the playback of the video requires the
autoplay prop. While autoplay of media serves a useful purpose, it should be used carefully and only when needed. In order to give users control over this, browsers often provide various forms of autoplay blocking.
Autoplay blocking is not applied to video elements when the source media doesn't have an audio track or is muted.
Gestalt Video provides a comprehensive API to handle gracefully autoplay blocking and prevent UI and/or client errors. The example below shows how to correctly handle autoplay error detection.
autoplay is set, use
onPlay to detect when the video starts playing and display the pause control accordingly. In case
autoplay gets blocked,
onPlay would never get triggered and controls will still display the play control.
onPlayError is another error-handling callback. In this case,
onPlayError detects if the HTMLMediaElement.play() method fails. HTMLMediaElement.play() returns a Promise and
onPlayError catches the error if the Promise is rejected. Display the pause control if any error is detected.
autoplay is set, don't set the initial
playing state to true as both will attempt to autoplay the video. We recommend setting
onPlay to detect when the video is played and setting
playing to true. If the initial
playing state is set to true, don't set
autoplay. If both
autoplay and the initial
playing state are set to true,
autoplay has preference.
For more information about autoplay, check the MDN Web Docs: video, MDN Web Docs: HTMLMediaElement.autoplay, and the MDN Web Docs: Autoplay guide for media and Web Audio APIs.
Video components can show a control bar to users in order to allow them access to certain features such as play/pause, timestamps, mute, and fullscreen. Pass in the
controls prop to make them appear. The Video
controls are custom; they aren't the native video controls.
Video component can show components in the
children prop on top of the html video element, while under the controls.
The children of Video aren't same as the children of the html video element; they're "outside" the html video element.
Video is robust enough to handle any updates, such as changing the source, volume, or speed.
Multiple video sources
Not all browsers support the same video encoding types. If you have multiple video file sources, you can pass them as a list to Video in the order you want the HTML video tag to use as fallbacks.
Component quality checklist
Component is live in Figma, however may not be available for all platforms.
Component is available in code for web and mobile web.
Component is not currently available in code for iOS.
Component is not currently available in code for Android.