Skip to content
ilinxa/pro-ui

Video Player

alphav0.3.0

Video player — seek bar, captions, fullscreen, buffering and error states with URL refresh, autoplay groups, composable controls, and double-tap gestures.

Category: MediaUpdated: 2026-10-24Created: 2026-05-02Author: ilinxa

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

Initialize shadcn (once per project)Seeds lib/utils.ts and components.json. Skip if you've already used any shadcn component.
pnpm dlx shadcn@latest init
Install the component
pnpm dlx shadcn@latest add @ilinxa/video-player

Add -fixtures for dummy data:

pnpm dlx shadcn@latest add @ilinxa/video-player-fixtures

CLI 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

demo.tsxtsx
"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=&quot;demo-feed&quot;</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=&quot;anonymous&quot;</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=&quot;rtl&quot;</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=&quot;tr&quot;</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=&#123;false&#125;</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} and showTime={false} to restore the 0.2 look.
  • Single tap is deferred 300 ms only when onDoubleTap is set (to tell it from a double tap). Without it a tap toggles playback at once.
  • onEnded without loop no longer loops. loop defaults to true, or to false when onEnded is passed. Pass loop explicitly to override.
  • DEFAULT_VIDEO_PLAYER_LABELS is now defaultVideoPlayerLabels. 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 pass labels.

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. A renderVideoElement slot for full takeover is not implemented (possible future addition).
  • Don't expect a volume slider / PiP in the default controls. Add via renderControls if needed (fullscreen is showFullscreen).
  • Don't expect HLS / DASH / streaming format support — raw <video src> only.
  • Don't hand-roll the spinner / error overlay — the default controls (and VideoPlayerStatus in 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 labels if you care about React.memo — hoist the labels object to module scope. Same for tracks arrays.

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, and autoPlayInView is disabled.
  • Custom renderControlsis the consumer's responsibility — preserve aria-pressed on toggle buttons + aria-label on 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

Tags

video-playervideomediaplayercarousel

Dependencies

shadcn primitives: button
npm peer deps: lucide-react@^1.11.0