Skip to content
Tutorials Center
My learning

Topics

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.

JSX
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

Custom play and pause buttons
Audio with a play counter

Syntax

JSX
<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, muted and playsInline for a silent background clip, and always handle the rejected promise from play().
  • muted is a property. React sets muted on 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.
  • timeupdate fires 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 paused or currentTime during 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() and pause() in an event handler, or in an effect that depends on the state, and keep the state updated from onPlay and onPause so the Space key and the native controls stay in sync.
  • Changing src. Setting a new src loads the new file and resets the position. With <source> children, React does not reload when they change: call load() through the ref, or give the element a key.
  • 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.