react-max-player

A custom video player component for React applications. It supports multi-quality switching, video chapters, custom subtitles, and is fully themable.

Features

• Custom video controls and UI
• Quality switching (e.g., 4K, 1080p, 720p)
• Video chapters and timeline markers
• Keyboard shortcuts support
• Picture-in-Picture and Fullscreen controls
• Written in TypeScript

Installation

npm install react-max-player

(You can also use yarn or pnpm)

Usage

Styles are injected automatically, so you just need to import the component.

import { VideoPlayer } from "react-max-player";

function App() {
  return (
    <VideoPlayer
      src="https://example.com/video.mp4"
      title="My Custom Video"
    />
  );
}

Advanced: Qualities & Chapters

If you have multiple resolutions or want to split the video into chapters:

import { VideoPlayer, Chapter, VideoQuality } from "react-max-player";

const qualities: VideoQuality[] = [
  { label: "1080p", value: "1080", src: "video_1080.mp4" },
  { label: "720p", value: "720", src: "video_720.mp4" },
];

const chapters: Chapter[] = [
  { title: "Intro", startTime: 0, endTime: 45 },
  { title: "Main Part", startTime: 46, endTime: 120 },
];

function App() {
  return (
    <VideoPlayer
      src={qualities[0].src}
      qualities={qualities}
      chapters={chapters}
      title="Advanced Sample"
      enableKeyboardShortcuts={true}
    />
  );
}

Theming and Customization

You can customize almost every part of the player using the controlOptions prop:

<VideoPlayer
  theme="dark"
  controlOptions={{
    seekBarStyle: {
      playedColor: "#3b82f6",
      bufferedColor: "rgba(255, 255, 255, 0.2)",
    },
    showPictureInPictureButton: false
  }}
/>

Controls visibility behavior

By default, control panel stays visible in normal mode (better for zoomed or compact layouts).
If you want fullscreen auto-hide behavior, enable it explicitly:

<VideoPlayer
  src="https://example.com/video.mp4"
  autoHideControls={true}
/>

Local Development

If you want to contribute or test the playground locally:

git clone https://github.com/AsadbekAbdullayev/react-max-player.git
cd react-max-player/demo
npm install
npm run dev

Migration

Upgrading from pre-1.1 releases

• Control panel behavior changed: controls stay visible in normal mode by default.
• To enable fullscreen auto-hide, pass autoHideControls={true}.
• If you previously relied on implicit auto-hide everywhere, set this prop explicitly in your wrapper component.

FAQ

Why does playback not start after switching demo cases?

Recent versions fix stale play state issues by using the actual media element state (paused/ended) in togglePlay.

Do I need to import CSS manually?

No. Styles are injected automatically in the package build.

Which React versions are supported?

react-max-player supports React 18 and 19. CI includes a compatibility matrix for both versions.

Troubleshooting

Controls are not visible in local demo

• Run demo with forced cache refresh: npm --prefix demo run dev -- --force
• Hard refresh browser (Ctrl+F5)
• Ensure the opened port matches the active Vite terminal output.

npm publish fails on prepublish checks

• Run npm run release:verify
• Make sure CHANGELOG.md contains a header matching package.json version (for example: ## [1.1.0])
• Verify package contents with npm run pack:check

License

MIT