React Reference ยท Built-in DOM Components
The video and audio elements in React
Reference for video and audio in React: control playback with a ref, listen to media events, handle autoplay rules and the muted prop, and avoid mistakes.
<video> and <audio> embed media in a page. They share one DOM interface, HTMLMediaElement, which has methods such as play() and pause(), properties such as currentTime, duration and paused, and a long list of events. In React you render the element with ordinary props (src, controls, poster, loop, muted) and reach for a ref when you need to call methods or read live values.
Most media properties change by themselves while the file plays. They are not React state, so do not read them while rendering. Listen to events (onPlay, onPause, onTimeUpdate, onEnded) and copy the values you want to show into state.
const ref = useRef(null); <video ref={ref} src="/samples/media/fractal.mp4" controls onEnded={() => console.log('done')} /> <button onClick={() => ref.current.play()}>Play</button>
Try it
Syntax
<video src={url} controls autoPlay loop muted playsInline preload="metadata" poster={image} /> <audio src={url} controls />
| Name | Description |
|---|---|
src |
Address of the media file. Use <source> children instead to offer several formats. |
controls |
Shows the browser's own control bar. |
autoPlay, loop, muted, playsInline |
Boolean props. autoPlay is the camelCase spelling of autoplay. |
preload |
"none", "metadata" or "auto": how much to fetch before playback. |
poster |
(video only) Image shown before playback starts. |
crossOrigin |
Needed for <track> captions or canvas pixel reads from another origin. |
| Event props | onLoadedMetadata, onCanPlay, onPlay, onPlaying, onPause, onSeeking, onSeeked, onTimeUpdate, onVolumeChange, onWaiting, onEnded, onError and more. |
Methods (via ref): play() returns a promise; pause(), load() and canPlayType(type) return nothing or a string. Properties: paused, currentTime, duration, volume, playbackRate, readyState, ended, error.
Errors: play() rejects with NotAllowedError when the browser blocks playback without a user gesture, and with AbortError if pause() or a new load interrupts it. duration is NaN until metadata has loaded.
Usage notes
- Autoplay rules. Browsers usually allow autoplay only for muted media, or after the user has interacted with the page. Combine
autoPlay,mutedandplaysInlinefor a silent background clip, and always handle the rejected promise fromplay(). mutedis a property. React setsmutedon the DOM node instead of rendering the attribute, so the markup you see in the Elements panel may not show it. Behavior is correct; this only affects inspection and some tests.timeupdatefires a few times per second. Storing the time in state re-renders at that rate. Keep the component small, or update a ref and show the time only where needed.- Do not read
pausedorcurrentTimeduring render. They are not part of React's data flow and can change between renders. Use events plus state. - Controlled playback. To drive playback from state, call
play()andpause()in an event handler, or in an effect that depends on the state, and keep the state updated fromonPlayandonPauseso the Space key and the native controls stay in sync. - Changing
src. Setting a newsrcloads the new file and resets the position. With<source>children, React does not reload when they change: callload()through the ref, or give the element akey. - Captions and accessibility. Provide
<track kind="captions">for speech, and a text alternative for audio-only content. Do not autoplay sound. - Cleanup. If you start network work or listeners tied to a media element in an effect, clean them up; media elements can keep downloading after unmount unless you set
src=""or pause them.
Related
ref, Event handler props,<img>, useRef- Lessons: useRef, Refs and imperative handles