Video Player
alphav0.3.0Video player — seek bar, captions, fullscreen, buffering and error states with URL refresh, autoplay groups, composable controls, and double-tap gestures.
Context
Use anywhere user-generated or editorial video plays — Instagram-post media, story viewers, news article inline videos, event recordings, product previews. The isActive prop pauses the video cleanly when its slide goes off-screen, so consumers (carousels, story viewers) coordinate playback via a single boolean. Custom control UI via the renderControls slot; default overlay matches the kasder play/pause/mute pattern with auto-hide. Double-tap callback fires through useDoubleTap (also exported standalone for non-video double-tap-to-like). Migration origin: kasder kas-social-front-v0 PostVideoPlayer.tsx; second ship in the 8-component social-posts-system arc; first occupant of the `media` category.
Installation
pnpm dlx shadcn@latest initpnpm dlx shadcn@latest add @ilinxa/video-playerAdd -fixtures for dummy data:
pnpm dlx shadcn@latest add @ilinxa/video-player-fixturesCLI can't resolve @ilinxa? The namespace is listed in the official shadcn registry directory, so current CLIs need no configuration. If yours can't resolve it (older or pinned versions, self-hosted mirrors), register it manually in components.json:
"registries": {
"@ilinxa": "https://ui.ilinxa.com/r/{name}.json"
}Preview
Seek bar and time are on by default; before playback the idle duration badge shows. The corner pause and mute buttons are the prototype look. Controls auto-hide after 2s during playback — hover or move the mouse to bring them back.
Demo source
"use client"; import { useRef, useState, type ReactNode } from "react";import { Pause, Play } from "lucide-react";import { Button } from "@/components/ui/button";import { Switch } from "@/components/ui/switch";import { Tabs, TabsContent, TabsTrigger } from "@/components/ui/tabs";import { SwipeTabsList } from "@/components/site/swipe-tabs-list";import { cn } from "@/lib/utils";import { VideoPlayer } from "./video-player";import { VideoPlayerMuteButton, VideoPlayerPlayButton, VideoPlayerSeekBar, VideoPlayerStatus, VideoPlayerTime,} from "./index";import { SAMPLE_CAPTIONED_VIDEO_URL, SAMPLE_LOOP_VIDEO_URL, SAMPLE_POSTER_URL, SAMPLE_RTL_CAPTION, SAMPLE_TRACKS_EN, SAMPLE_TRACKS_MULTI, SAMPLE_VIDEO_URL, SAMPLE_VIDEO_URL_B, SAMPLE_VIDEO_URL_C,} from "./dummy-data";import type { VideoPlayerHandle, VideoState } from "./types"; /** A URL that 404s on purpose, for the error-refresh demo. */const BROKEN_VIDEO_URL = "https://test-videos.co.uk/vids/does-not-exist.mp4"; function formatTime(seconds: number): string { if (!Number.isFinite(seconds)) return "0:00"; const m = Math.floor(seconds / 60); const s = Math.floor(seconds % 60); return `${m}:${s.toString().padStart(2, "0")}`;} function Frame({ children }: { children: ReactNode }) { return <div className="aspect-video overflow-hidden rounded-md">{children}</div>;} function CustomControlsRenderer({ isPlaying, duration, currentTime, togglePlay,}: VideoState) { const progress = duration > 0 ? (currentTime / duration) * 100 : 0; return ( <div className="pointer-events-none absolute inset-0 flex flex-col justify-end"> <div className="pointer-events-auto bg-linear-to-t from-black/70 to-transparent p-3"> <div className="mb-2 flex items-center gap-2"> <Button type="button" variant="secondary" size="icon" className="h-8 w-8 rounded-full bg-background/80" onClick={togglePlay} aria-label={isPlaying ? "Pause" : "Play"} > {isPlaying ? ( <Pause className="h-4 w-4" aria-hidden="true" /> ) : ( <Play className="h-4 w-4 fill-current" aria-hidden="true" /> )} </Button> <span className="font-mono text-xs text-white tabular-nums"> {formatTime(currentTime)} / {formatTime(duration)} </span> </div> <div className="h-1 w-full overflow-hidden rounded-full bg-white/20"> <div className="h-full bg-primary transition-[width] duration-150" style={{ width: `${progress}%` }} /> </div> </div> </div> );} function CarouselDemo() { const videos = [SAMPLE_VIDEO_URL, SAMPLE_VIDEO_URL_B, SAMPLE_VIDEO_URL_C]; const [activeIdx, setActiveIdx] = useState(0); return ( <div className="space-y-4"> <div className="grid gap-3 sm:grid-cols-3"> {videos.map((src, idx) => ( <div key={src} className={cn( "aspect-video overflow-hidden rounded-md ring-2 transition-all", idx === activeIdx ? "ring-primary" : "opacity-60 ring-transparent", )} > <VideoPlayer src={src} isActive={idx === activeIdx} autoPlay /> </div> ))} </div> <div className="flex flex-wrap items-center gap-2"> <span className="text-xs text-muted-foreground">Active slide:</span> {videos.map((_, idx) => ( <Button key={idx} type="button" size="sm" variant={idx === activeIdx ? "default" : "outline"} onClick={() => setActiveIdx(idx)} > Video {idx + 1} </Button> ))} </div> <p className="text-xs text-muted-foreground"> Only the active slide plays. Switching pauses the previous video cleanly via the <code>isActive</code> prop — exactly the contract that <code>media-carousel</code> will use. </p> </div> );} function ErrorRefreshDemo() { const [refreshes, setRefreshes] = useState(0); return ( <div className="grid gap-4 sm:grid-cols-2"> <div className="space-y-2"> <Frame> <VideoPlayer src={BROKEN_VIDEO_URL} onMediaError={() => { setRefreshes((n) => n + 1); return new Promise<string>((resolve) => setTimeout(() => resolve(SAMPLE_VIDEO_URL), 1500), ); }} /> </Frame> <p className="text-xs text-muted-foreground"> Refreshes requested: {refreshes}. The 404 calls{" "} <code>onMediaError</code> once; the spinner shows for 1.5 s, then the returned URL plays. </p> </div> <div className="space-y-2"> <Frame> <VideoPlayer src={BROKEN_VIDEO_URL} onMediaError={() => undefined} /> </Frame> <p className="text-xs text-muted-foreground"> <code>onMediaError</code> returns nothing, so the error overlay shows with a Retry button. </p> </div> </div> );} function AutoplayGroupDemo() { const clips = [SAMPLE_VIDEO_URL, SAMPLE_VIDEO_URL_B, SAMPLE_VIDEO_URL_C]; return ( <div className="space-y-3"> <div className="max-h-96 space-y-6 overflow-y-auto rounded-md border border-border p-3"> {clips.map((src) => ( <Frame key={src}> <VideoPlayer src={src} autoPlayInView autoplayGroup="demo-feed" /> </Frame> ))} </div> <p className="text-xs text-muted-foreground"> Scroll the column: a player plays (muted) once half of it is visible and pauses when it leaves. All three share{" "} <code>autoplayGroup="demo-feed"</code>, so only one plays at a time. Reduced motion turns autoplay-in-view off. </p> </div> );} function ControlledMuteDemo() { const [muted, setMuted] = useState(true); return ( <div className="space-y-3"> <label className="flex items-center gap-2 text-sm"> <Switch checked={!muted} onCheckedChange={(on) => setMuted(!on)} /> Sound on (feed-wide) </label> <div className="grid gap-3 sm:grid-cols-2"> <Frame> <VideoPlayer src={SAMPLE_VIDEO_URL} muted={muted} onMutedChange={setMuted} /> </Frame> <Frame> <VideoPlayer src={SAMPLE_VIDEO_URL_B} muted={muted} onMutedChange={setMuted} /> </Frame> </div> <p className="text-xs text-muted-foreground"> One <code>muted</code> state shared by two players. Each mute button calls <code>onMutedChange</code> instead of changing the element, so the switch and both players stay in step. </p> </div> );} function ComposedDemo() { const ref = useRef<VideoPlayerHandle>(null); return ( <div className="space-y-3"> <Frame> <VideoPlayer ref={ref} src={SAMPLE_VIDEO_URL} poster={SAMPLE_POSTER_URL} renderControls={() => ( <> <VideoPlayerStatus /> <div className="absolute inset-x-0 bottom-0 flex flex-col gap-2 p-3"> <VideoPlayerSeekBar /> <div className="flex items-center gap-2"> <VideoPlayerPlayButton /> <VideoPlayerTime /> <VideoPlayerMuteButton className="ms-auto" /> </div> </div> </> )} /> </Frame> <div className="flex flex-wrap items-center gap-2"> <Button type="button" size="sm" variant="outline" onClick={() => void ref.current?.play()}> play() </Button> <Button type="button" size="sm" variant="outline" onClick={() => ref.current?.pause()}> pause() </Button> <Button type="button" size="sm" variant="outline" onClick={() => ref.current?.seek(5)}> seek(5) </Button> </div> <p className="text-xs text-muted-foreground"> A lighter overlay built from the flat parts (status, seek bar, play, time, mute) and placed with logical utilities. The buttons drive the player through its <code>ref</code> handle. </p> </div> );} export default function VideoPlayerDemo() { return ( <Tabs defaultValue="default"> <SwipeTabsList> <TabsTrigger value="default">Default</TabsTrigger> <TabsTrigger value="captions">Captions</TabsTrigger> <TabsTrigger value="fullscreen">Fullscreen</TabsTrigger> <TabsTrigger value="error">Error refresh</TabsTrigger> <TabsTrigger value="autoplay">Autoplay group</TabsTrigger> <TabsTrigger value="muted">Controlled mute</TabsTrigger> <TabsTrigger value="composed">Composed controls</TabsTrigger> <TabsTrigger value="custom-controls">Custom controls</TabsTrigger> <TabsTrigger value="rtl">RTL</TabsTrigger> <TabsTrigger value="decorative">Decorative</TabsTrigger> <TabsTrigger value="carousel">isActive (carousel)</TabsTrigger> </SwipeTabsList> <TabsContent value="default" className="mt-6"> <Frame> <VideoPlayer src={SAMPLE_VIDEO_URL} poster={SAMPLE_POSTER_URL} /> </Frame> <p className="mt-3 text-xs text-muted-foreground"> Seek bar and time are on by default; before playback the idle duration badge shows. The corner pause and mute buttons are the prototype look. Controls auto-hide after 2s during playback — hover or move the mouse to bring them back. </p> </TabsContent> <TabsContent value="captions" className="mt-6 space-y-3"> <div className="grid gap-3 sm:grid-cols-2"> <Frame> <VideoPlayer src={SAMPLE_CAPTIONED_VIDEO_URL} tracks={SAMPLE_TRACKS_MULTI} crossOrigin="anonymous" /> </Frame> <Frame> <VideoPlayer src={SAMPLE_CAPTIONED_VIDEO_URL} tracks={SAMPLE_TRACKS_EN} crossOrigin="anonymous" /> </Frame> </div> <p className="text-xs text-muted-foreground"> Left: two tracks give a captions menu. Right: one track gives a toggle. Cross-origin caption files need{" "} <code>crossOrigin="anonymous"</code> and a CORS-enabled video host; never set it on a clip served without CORS headers. </p> </TabsContent> <TabsContent value="fullscreen" className="mt-6"> <Frame> <VideoPlayer src={SAMPLE_VIDEO_URL} poster={SAMPLE_POSTER_URL} showFullscreen /> </Frame> <p className="mt-3 text-xs text-muted-foreground"> <code>showFullscreen</code> adds the button; it stays hidden where no fullscreen API exists. </p> </TabsContent> <TabsContent value="error" className="mt-6"> <ErrorRefreshDemo /> </TabsContent> <TabsContent value="autoplay" className="mt-6"> <AutoplayGroupDemo /> </TabsContent> <TabsContent value="muted" className="mt-6"> <ControlledMuteDemo /> </TabsContent> <TabsContent value="composed" className="mt-6"> <ComposedDemo /> </TabsContent> <TabsContent value="custom-controls" className="mt-6"> <Frame> <VideoPlayer src={SAMPLE_VIDEO_URL} poster={SAMPLE_POSTER_URL} renderControls={(state) => <CustomControlsRenderer {...state} />} /> </Frame> <p className="mt-3 text-xs text-muted-foreground"> The default control overlay is fully replaced via{" "} <code>renderControls</code> — slot receives full{" "} <code>VideoState</code> (isPlaying, currentTime, duration, togglePlay, etc.). </p> </TabsContent> <TabsContent value="rtl" className="mt-6 space-y-3"> <div dir="rtl" lang="ar" className="rounded-xl border border-border bg-card p-4"> <p className="mb-3 text-sm">{SAMPLE_RTL_CAPTION}</p> <Frame> <VideoPlayer src={SAMPLE_VIDEO_URL} poster={SAMPLE_POSTER_URL} /> </Frame> </div> <p className="text-xs text-muted-foreground"> No <code>dir</code> prop: direction comes from the ancestor{" "} <code>dir="rtl"</code>. The seek bar fills from the right and the arrow keys are mirrored. </p> <div className="max-w-md space-y-2"> <Frame> <VideoPlayer src={SAMPLE_VIDEO_URL_B} locale="tr" /> </Frame> <p className="text-xs text-muted-foreground"> <code>locale="tr"</code> formats the time text for Turkish. </p> </div> </TabsContent> <TabsContent value="decorative" className="mt-6"> <Frame> <VideoPlayer src={SAMPLE_LOOP_VIDEO_URL} controls={false} autoPlay loop /> </Frame> <p className="mt-3 text-xs text-muted-foreground"> <code>controls={false}</code> + <code>autoPlay</code> +{" "} <code>loop</code> — silent decorative background. No control overlay and no seek keys; click-to-toggle and Space / M still work when focused. </p> </TabsContent> <TabsContent value="carousel" className="mt-6"> <CarouselDemo /> </TabsContent> </Tabs> );} Usage
When to use
Reach for VideoPlayer anywhere user-generated or editorial video plays — Instagram-post media, story viewers, news article inline videos, event recordings, product previews. The isActive prop pauses cleanly when the video goes off-screen, so consumers (carousels, story viewers) coordinate playback via a single boolean. Custom control UI via the renderControls slot; default overlay matches the kasder-style corner pause / mute pattern, plus a seek bar and time, with auto-hide.
Basic example
import { VideoPlayer } from "@/components/video-player";
export function Example() {
return (
<div className="aspect-video">
<VideoPlayer src={post.videoUrl} poster={post.posterUrl} />
</div>
);
}Carousel coordination via isActive
The host (carousel / story viewer) tracks which slide is current and sets isActive per slide. Inactive videos pause cleanly; active videos resume on consumer-driven gesture (no auto-resume).
{slides.map((item, idx) => (
<CarouselSlide key={item.id}>
{item.type === "video" ? (
<VideoPlayer
src={item.url}
poster={item.poster}
isActive={idx === currentIndex}
onDoubleTap={() => onLike(post.id)}
/>
) : (
<img src={item.url} alt={item.alt} />
)}
</CarouselSlide>
))}Decorative background loop
<VideoPlayer
src="/hero/loop.mp4"
controls={false}
autoPlay
loop
/>Custom controls via renderControls
The slot fully replaces the default overlay. Receives the entire VideoState (isPlaying, isMuted, isLoaded, duration, currentTime, togglePlay, toggleMute). The video ref is intentionally NOT exposed — it would let consumers bypass our state machine.
<VideoPlayer
src={reel.videoUrl}
renderControls={({ isPlaying, currentTime, duration, togglePlay }) => (
<ReelsControlOverlay
isPlaying={isPlaying}
progress={currentTime / duration}
onPlayToggle={togglePlay}
/>
)}
/>Captions via tracks
<VideoPlayer
src={article.videoUrl}
poster={article.videoPoster}
objectFit="contain"
controlsAutoHideMs={0}
tracks={[
{ kind: "captions", src: "/captions/en.vtt", srcLang: "en", label: "English", default: true },
{ kind: "captions", src: "/captions/tr.vtt", srcLang: "tr", label: "Türkçe" },
]}
labels={{ videoLabel: "Article video: Sustainable cities" }}
/>Seek bar, time and fullscreen
The default overlay shows a seek bar and elapsed / total time. Before playback an idle duration badge shows; pass durationHint (seconds, from your API) to fill it before metadata loads. showFullscreen adds a fullscreen button (hidden when the browser has no fullscreen API). seekStep sets the seconds per arrow-key step (default 5; ← / → are mirrored in RTL). controls={false} removes the overlay and the seek keys; Space and M still work when the video is focused.
<VideoPlayer
src={post.videoUrl}
durationHint={post.durationSeconds}
showFullscreen
seekStep={10}
/>Captions and crossOrigin
One track renders a captions toggle; several render a menu with an Off item. A caption file on another origin needs crossOrigin="anonymous" on the player and CORS headers on both the video and the caption file. Do not set crossOrigin on a video host that sends no CORS header — the video would fail to load.
<VideoPlayer
src={cdnVideoUrl}
crossOrigin="anonymous"
tracks={[
{ kind: "captions", src: cdnEnVtt, srcLang: "en", label: "English" },
{ kind: "subtitles", src: cdnTrVtt, srcLang: "tr", label: "Türkçe" },
]}
/>Refreshing an expired URL with onMediaError
When the media errors, onMediaError(src) is called once per src. Return (or resolve) a new URL and the source is replaced; playback resumes at the same time and play state. While the promise is pending the player shows its buffering state. A void answer, a rejection or a second error shows the error overlay with a Retry button (retry() reloads and resumes). A new src resets the once-per-src budget. onError still fires on every error.
<VideoPlayer
src={signedUrl}
onMediaError={async () => {
const fresh = await api.resignVideo(post.id);
return fresh.url; // return nothing to show the error overlay
}}
/>Controlled mute: muted + onMutedChange
muted defaults to true. Passing onMutedChange as well makes it controlled: the prop wins on every render and the mute button calls onMutedChange instead of changing the element. Without onMutedChange, the viewer's toggle applies until the prop next changes. Use it for a feed-wide "sound on" switch.
const [muted, setMuted] = useState(true);
<VideoPlayer src={a} muted={muted} onMutedChange={setMuted} />
<VideoPlayer src={b} muted={muted} onMutedChange={setMuted} />Long feeds: autoplay in view, groups, preload
autoPlayInView plays the video (muted) while at least autoPlayThreshold (default 0.5) of it is visible and pauses it when it leaves. Give players the same autoplayGroup and at most one plays: a player that starts pauses the others. Reduced motion disables autoplay-in-view. For long lists pass preload="none" with a durationHint so off-screen videos load nothing but still show a duration.
{posts.map((post) => (
<VideoPlayer
key={post.id}
src={post.videoUrl}
autoPlayInView
autoplayGroup="home-feed"
preload="none"
durationHint={post.durationSeconds}
/>
))}loop and onEnded
loop defaults to true — unless onEnded is passed, in which case it defaults to false (a looping video never ends). Pass loop yourself to force either.
<VideoPlayer src={clip} onEnded={() => goToNextSlide()} />Lifecycle and progress callbacks
onPlay / onPause / onEnded / onLoadedMetadata(duration) / onError(mediaError) mirror the element. onTimeUpdate(currentTime, duration) and onProgress({ currentTime, duration, buffered }) report media time, throttled to one call per animation frame; onProgress also fires on the element's progress event with the buffered spans. Style hooks: className (wrapper), videoClassName, controlsClassName (default overlay only).
<VideoPlayer
src={video.url}
onProgress={({ currentTime, duration }) => report(currentTime / duration)}
onLoadedMetadata={(d) => setDuration(d)}
/>Flat parts and the ref handle
Inside renderControls you can compose the flat parts instead of building a UI from VideoState: VideoPlayerPlayButton (size "sm" | "lg"), VideoPlayerMuteButton, VideoPlayerSeekBar, VideoPlayerTime, VideoPlayerDurationBadge, VideoPlayerFullscreenButton, VideoPlayerCaptionsButton and VideoPlayerStatus (spinner / error overlay — mount it or you lose both). Each takes an optional className; position them with logical utilities (ms-auto, inset-x-0). useVideoPlayer() reads the same context from your own part. The ref handle exposes play(), pause(), seek(seconds), toggleMute() and toggleFullscreen(); it never exposes the <video> element.
const ref = useRef<VideoPlayerHandle>(null);
<VideoPlayer
ref={ref}
src={clip}
renderControls={() => (
<>
<VideoPlayerStatus />
<div className="absolute inset-x-0 bottom-0 flex items-center gap-2 p-3">
<VideoPlayerPlayButton />
<VideoPlayerSeekBar />
<VideoPlayerTime />
<VideoPlayerMuteButton />
</div>
</>
)}
/>
ref.current?.seek(30);Labels, locale and RTL
Every string is a typed label: pass any subset via labels (an undefined value never erases a default); defaultVideoPlayerLabels is exported for composition. locale (BCP-47, default "en"; an invalid tag falls back to "en") formats the time text; formatDuration overrides it. Direction follows the ancestor's dir (or the dir prop): the seek bar fills from the end side and ← / → are mirrored.
<div dir="rtl" lang="ar">
<VideoPlayer src={clip} locale="ar" labels={{ play: "تشغيل", pause: "إيقاف" }} />
</div>Upgrading to 0.3.0
- Seek bar and time are on by default. Pass
showSeekBar={false}andshowTime={false}to restore the 0.2 look. - Single tap is deferred 300 ms only when
onDoubleTapis set (to tell it from a double tap). Without it a tap toggles playback at once. onEndedwithoutloopno longer loops.loopdefaults to true, or to false whenonEndedis passed. Passloopexplicitly to override.DEFAULT_VIDEO_PLAYER_LABELSis nowdefaultVideoPlayerLabels. The old name stays as a deprecated alias for one minor.- New labels (
seek,position,timeDisplay,durationBadge,fullscreen,exitFullscreen,captions,captionsMenu,captionsOff,buffering,error,retry) — translate them if you passlabels.
Localized labels
const TR_LABELS = {
play: "Oynat",
pause: "Duraklat",
mute: "Sesi Kapat",
unmute: "Sesi Aç",
videoLabel: "Etkinlik videosu",
};
<VideoPlayer src={event.recordingUrl} labels={TR_LABELS} />Standalone useDoubleTap hook
Exported from index.ts for non-video double-tap-to-like contexts (image carousels, photo viewers, card double-tap-to-favorite).
import { useDoubleTap } from "@/components/video-player";
function PhotoWithLike({ src, onLike }: { src: string; onLike: () => void }) {
const handleTap = useDoubleTap(onLike);
return <img src={src} onClick={handleTap} className="..." />;
}
// Or with a custom window:
const handleTap = useDoubleTap(onLike, { windowMs: 400 });Anti-patterns
- Don't expect a video ref in
renderControls— exposing it would let consumers bypass our state machine and cause desync. State + dispatchers only. ArenderVideoElementslot for full takeover is not implemented (possible future addition). - Don't expect a volume slider / PiP in the default controls. Add via
renderControlsif needed (fullscreen isshowFullscreen). - Don't expect HLS / DASH / streaming format support — raw
<video src>only. - Don't hand-roll the spinner / error overlay — the default controls (and
VideoPlayerStatusin composed controls) show them. - Don't auto-resume when
isActiveflips back to true. The component pauses on deactivation but doesn't auto-play on reactivation — consumer drives the play gesture. - Don't inline define
labelsif you care aboutReact.memo— hoist the labels object to module scope. Same fortracksarrays.
Accessibility
<video tabIndex={0}>— keyboard focusable; Space toggles play/pause, M toggles mute (focus-only, per Q-P4 lock).- Mute toggle gets
aria-pressed={isMuted}; label switches between "Mute" (action) and "Unmute" (action) so AT announces the action that the button will perform. - Caption tracks via the
tracksprop expose in the browser's native subtitle UI (CC button in fullscreen). - Under
prefers-reduced-motion: reduce, the auto-hide timer is skipped entirely — controls stay visible, andautoPlayInViewis disabled. - Custom
renderControlsis the consumer's responsibility — preservearia-pressedon toggle buttons +aria-labelon icon-only triggers.
Features
- Muted autoplay-friendly defaults (muted=true, loop=true unless onEnded is passed, playsInline=true)
- isActive prop pauses cleanly when false (carousel coordination)
- Seek bar (role=slider) driven by media time, with buffered ranges, direction-aware arrow keys, Home/End and pointer drag
- Elapsed / total time and an idle duration badge through locale + formatDuration (durationHint for preload=none)
- Opt-in fullscreen (container requestFullscreen, iOS webkitEnterFullscreen fallback; hidden when neither exists)
- Captions control for tracks: a toggle for one track, a keyboard-operable menu for several; crossOrigin pass-through
- Buffering spinner + error overlay with Retry; onMediaError refreshes an expired URL once per src and resumes at the same time and play state
- Opt-in autoPlayInView (muted, visibility threshold) with autoplayGroup — at most one player per group plays; off under reduced motion
- Controlled muted via onMutedChange (feed-wide sound preference); uncontrolled by default
- Imperative ref handle: play / pause / seek / toggleMute / toggleFullscreen
- Flat parts for renderControls: VideoPlayerPlayButton, MuteButton, SeekBar, Time, DurationBadge, FullscreenButton, CaptionsButton, Status
- Default overlay: big play button + bottom-start pause + bottom-end mute + seek bar row; 2s auto-hide that wakes on pointer, tap, focus and keys; hidden controls take no clicks
- Double tap: with onDoubleTap a single tap waits out the 300ms window, so a double tap never plays-then-pauses
- Keyboard: Space=play/pause, M=mute, ←/→ seek while controls render (focus-required)
- rAF-throttled onTimeUpdate and onProgress ({ currentTime, duration, buffered })
- Lifecycle callbacks: onPlay / onPause / onEnded / onTimeUpdate / onProgress / onLoadedMetadata / onError
- Public useDoubleTap hook export (with an optional onSingleTap) for non-video consumers
- Typed labels (functions for values) + locale; dir prop or inherited direction; RTL-mirrored seek bar
- a11y: aria-label on <video>, aria-pressed toggles, slider valuetext, status / alert regions