A video player is an important part of many modern web applications, from online learning platforms and entertainment websites to live-streaming services. While the HTML5 <video> element provides basic playback functionality, React makes it easier to build reusable players with custom controls and interactive features.

In this tutorial, we'll explore how to build a simple React video player with play, pause, seek, volume, and mute controls. We'll use React hooks and the browser's native video capabilities without creating a large or complicated component.

Why Build a Custom Video Player in React?

The default browser video player is useful, but it does not always match an application's design or user experience requirements.

A custom React video player gives developers more control over:

  • Playback buttons and progress bars
  • Volume and mute controls
  • Video loading and playback states
  • Responsive layouts
  • Custom branding and interface design

For streaming applications, the player is only one part of the overall experience. Developers also need to consider how video content is delivered, how playback behaves under different network conditions, and how viewers interact with the application.

1. Set Up a React Project

We'll use Vite to create a React application.

Run the following commands in your terminal:

npm create vite@latest react-video-player -- --template react cd react-video-player npm install npm run dev 

Once the development server starts, open the local URL provided in your terminal.

You can now begin building your video player.

2. Understand the HTML5 Video Element

Before adding React controls, it helps to understand the HTML5 video element.

The browser already provides built-in playback functionality through the <video> element.

Here is a simple example:

<video src="/sample-video.mp4" controls width="640" playsinline ></video> 

The controls attribute displays the browser's default playback controls. However, when building a custom player, you may want to manage those controls yourself.

React allows you to access the video element directly and control its playback methods.

3. Access the Video Element with useRef

React's useRef hook allows you to reference a DOM element without triggering a component re-render whenever the reference changes.

For a video player, this is useful because you need direct access to methods such as play(), pause(), and currentTime.

Start by importing the required hooks:

import { useRef, useState } from "react"; const videoRef = useRef(null); const [isPlaying, setIsPlaying] = useState(false); 

Here:

  • videoRef stores a reference to the video element.
  • isPlaying tracks whether the video is currently playing.

You can connect the reference to your video element:

<video ref={videoRef} src="/sample-video.mp4" playsInline preload="metadata" /> 

The preload="metadata" attribute allows the browser to load basic video information without necessarily downloading the entire video immediately.

4. Add Play and Pause Controls

The next step is to add custom play and pause functionality.

The video element provides built-in JavaScript methods for controlling playback:

  • play() starts playback.
  • pause() pauses playback.

A simple toggle function looks like this:

const togglePlayback = async () => { const video = videoRef.current; if (video.paused) { await video.play(); } else { video.pause(); } }; 

You can connect the player's state to the video's playback events:

onPlay={() => setIsPlaying(true)} onPause={() => setIsPlaying(false)} 

This keeps the React state updated when playback starts or stops.

Remember that browsers may restrict autoplay with sound. Starting playback in response to a user's button click is generally more reliable.

5. Add a Seek Bar

A seek bar lets viewers move forward or backward through a video without restarting it.

The video element provides two useful properties:

  • currentTime: the current playback position in seconds.
  • duration: the total video length in seconds.

You can update the playback position when a viewer interacts with a range input:

videoRef.current.currentTime = Number(e.target.value); 

The range input can use the video's duration as its maximum value:

<input type="range" min="0" max={duration} value={currentTime} onChange={handleSeek} /> 

To keep the progress bar updated during playback, listen for the timeupdate event:

onTimeUpdate={(e) => setCurrentTime(e.currentTarget.currentTime) } 

You should also read the video's duration after its metadata loads:

onLoadedMetadata={(e) => setDuration(e.currentTarget.duration) } 

Together, these events help keep the seek bar synchronized with the video.

6. Add Volume and Mute Controls

A custom player should also allow viewers to adjust the sound.

The HTML5 video element provides a volume property that accepts a value between 0 and 1.

For example:

videoRef.current.volume = Number(e.target.value); 

A range input can be used to control the volume.

You can also toggle the muted state:

videoRef.current.muted = !videoRef.current.muted; 

These small controls make the player more flexible without requiring an additional video playback library.

7. Improve the Video Player Experience

Adding playback controls is only the beginning. A good video player should also provide a smooth and predictable viewing experience.

Here are some practical considerations:

Responsive design: The player should adjust to different screen sizes, including mobile phones, tablets, and desktop screens.

Loading feedback: Display a loading indicator when the video is buffering or preparing to play.

Error handling: Provide a useful message when a video cannot load or the media source is unavailable.

Accessible controls: Use clear button labels, keyboard-friendly interactions, and appropriate accessibility attributes.

Playback feedback: Make sure the play button, pause button, and progress bar reflect the actual playback state.

Network conditions can also affect the viewing experience. Adaptive bitrate streaming allows a player to adjust video quality according to the viewer's available bandwidth, helping reduce buffering. Learn more about adaptive bitrate streaming.

8. What About Large-Scale Video Streaming?

The examples above are suitable for learning the basics of a React video player. However, a production streaming application may need more than a basic HTML5 video element.

For example, applications with large audiences may need to consider:

  • Adaptive bitrate streaming
  • HLS or MPEG-DASH playback
  • Content delivery networks (CDNs)
  • Video access protection
  • Playback analytics
  • Reliable delivery during high-traffic events

HLS and MPEG-DASH are commonly used to deliver video across different devices and network conditions. These protocols work with video delivery infrastructure to help streaming applications serve content efficiently.

Content delivery networks distribute video content through geographically distributed servers, helping viewers access media from locations closer to them. Learn more about video CDN architecture.

Choosing the right technologies is also important when building a reliable streaming application. Explore the OTT tech stack to understand the technologies involved in developing a streaming platform.

These technologies work alongside the video player to support video delivery. A basic HTML5 player does not automatically provide every advanced streaming capability; additional playback support may be required depending on the format and browser.

Common Mistakes to Avoid

When developing a React video player, a few common mistakes can lead to unexpected behavior.

  • Not checking the video reference: Make sure videoRef.current exists before calling playback methods.
  • Ignoring playback errors: The play() method returns a promise, so handle possible failures in production applications.
  • Not updating playback state: Use video events to keep React state synchronized with the actual player.
  • Ignoring mobile behavior: Test playback and controls on different mobile browsers.
  • Overcomplicating the component: Start with essential controls and add advanced functionality only when needed.

Another mistake is overlooking performance under heavy traffic. When many viewers access the same video or live event simultaneously, bottlenecks can affect playback. Understanding live streaming performance can help developers prepare for these situations.

Keeping the player modular makes it easier to maintain and extend as the application grows.

Conclusion

Building a React video player does not require a complicated setup. By combining the HTML5 video element with React hooks such as useRef and useState, developers can create useful playback controls with relatively little code.

Start with the basics: play, pause, seeking, volume, and mute. Then improve the experience with responsive design, loading feedback, accessibility, and error handling.

For larger streaming applications, consider the wider infrastructure behind video delivery as well. A reliable player is important, but consistent playback also depends on how video content is prepared, delivered, and managed.