Props
Accessibility
Captions
Warning: Captions aren't currently supported.
Captions are intended for deaf and hard-of-hearing audiences. Captions are usually in the same language as the audio. Please, reade 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.
Labels
Video requires several accessibility labels for each video control: accessibilityMaximizeLabel
, accessibilityMinimizeLabel
, accessibilityMuteLabel
, accessibilityPauseLabel
, accessibilityPlayLabel
, accessibilityProgressBarLabel
and accessibilityUnmuteLabel
.
If the video contain captions, it also requires accessibilityHideCaptionsLabel
and accessibilityShowCaptionsLabel
.
.
Variants
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.
If 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.
If autoplay
is set, don't set the initial playing
state to true as both will attempt to autoplay the video. We recommend setting autoplay
, using 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 controls
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.
With children
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 updates
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.