Custom Video Player

A video player with a custom control bar that fades out automatically during playback, supporting scrub-to-seek, volume, fullscreen, and keyboard operation.

Loading preview…

npx shadcn@latest add "https://webberui.com/r/custom-video-player.json?t=<install token>"

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

Aspect ratioaspectRatio

Controls fade-out delay (ms)hideControlsDelay

2400

Auto-hide the controlsautoHide

Looploop

Muted initiallymuted

<CustomVideoPlayer />

Installation

npx shadcn@latest add "https://webberui.com/r/custom-video-player.json?t=<install token>"

Or, once registries are configured in components.json, install it as @webberui/custom-video-player.

Usage

import { CustomVideoPlayer } from "@/components/ui/custom-video-player";

<CustomVideoPlayer
  src="/videos/demo.mp4"
  poster="/videos/demo-poster.jpg"
  className="w-full max-w-2xl"
/>

Most browsers require muted alongside autoplay:

<CustomVideoPlayer src="/videos/loop.mp4" autoPlay loop muted />

Props

Prop	Type	Default	Description
`src`	`string`	—	Video source URL
`poster`	`string`	—	Cover image, shown before playback
`autoPlay`	`boolean`	`false`	Autoplay (usually needs `muted` alongside it)
`loop`	`boolean`	`false`	Loop playback
`muted`	`boolean`	`false`	Whether it starts muted
`hideControlsDelay`	`number`	`2400`	How many milliseconds of inactivity during playback before the control bar fades out
`autoHide`	`boolean`	`true`	Whether the control bar fades out automatically
`aspectRatio`	`string`	`"16 / 9"`	The container's CSS `aspect-ratio`
`label`	`string`	`"影片播放器"` (Video player)	Accessible label for the player container
`onPlayStateChange`	`(playing: boolean) => void`	—	Callback when the playback state changes
`className`	`string`	—	Appended to the container's className

How it works

The control bar fades out and hides the cursor while playing with no interaction, and reappears immediately on cursor movement, touch, focus, or a key press; it stays lit while paused or once playback ends.
The progress bar can be clicked to seek and dragged to scrub (using pointer capture, so it keeps working even if the cursor leaves the player).
Duration correction is built in: for streams or MediaRecorder blobs whose duration is Infinity, a recalculation is triggered automatically so the progress and the time display stay correct.
The volume slider is collapsed normally and expands when the mouse enters or focus lands on the volume area.

Accessibility

When the user has "reduce motion" enabled at the system level, the control bar's automatic fade-out is disabled and it stays lit, with transition durations set to zero.
Complete keyboard operation (once the player has focus):
- Space / K: play/pause
- ← / → (or J / L): back/forward 5 seconds
- ↑ / ↓: volume up/down
- Home / End: jump to the start/end
- M: toggle mute　F: toggle fullscreen
The progress bar is a role="slider" with aria-valuemin/max/now and aria-valuetext; every control button has an aria-label, and the mute and fullscreen buttons reflect their state with aria-pressed.