useVideo
Playback controls for a video ref.
Import
TypeScript
import { useVideo } from '@/hooks';API
Signature
useVideo(ref) → playback controls
When to use
Use useVideo instead of re-implementing the same pattern in multiple components.
SSR / Next.js
Client-only browser APIs.
Live playground
Edit the example and see it run against the real @/hooks package in this app.
Live playgroundEdit · run with real
@/hooks · useVideoEditor
function VideoPlayer() { const ref = useRef<HTMLVideoElement>(null); const v = useVideo(ref); return ( <div> <video ref={ref} src="/demo.mp4" /> <button onClick={() => void v.play()}>Play</button> <button onClick={v.pause}>Pause</button> </div> ); }
Preview
Implementation source
Full library source for useVideo — copy into your project when you are not installing a package yet.
hooks/media/useVideo.ts
import { useCallback, useEffect, useRef, useState } from 'react';
import type { RefObject } from 'react';
export interface UseVideoReturn {
playing: boolean;
muted: boolean;
time: number;
duration: number;
play: () => Promise<void>;
pause: () => void;
toggle: () => void;
setMuted: (muted: boolean) => void;
seek: (time: number) => void;
}
/** Bind playback controls to a video element ref. */
export function useVideo(
ref: RefObject<HTMLVideoElement | null>,
): UseVideoReturn {
const [playing, setPlaying] = useState(false);
const [muted, setMutedState] = useState(false);
const [time, setTime] = useState(0);
const [duration, setDuration] = useState(0);
const bound = useRef(false);
useEffect(() => {
const video = ref.current;
if (!video) return;
const onPlay = () => setPlaying(true);
const onPause = () => setPlaying(false);
const onTime = () => setTime(video.currentTime);
const onMeta = () => setDuration(video.duration || 0);
video.addEventListener('play', onPlay);
video.addEventListener('pause', onPause);
video.addEventListener('timeupdate', onTime);
video.addEventListener('loadedmetadata', onMeta);
bound.current = true;
return () => {
video.removeEventListener('play', onPlay);
video.removeEventListener('pause', onPause);
video.removeEventListener('timeupdate', onTime);
video.removeEventListener('loadedmetadata', onMeta);
};
}, [ref]);
const play = useCallback(async () => {
await ref.current?.play();
}, [ref]);
const pause = useCallback(() => ref.current?.pause(), [ref]);
const toggle = useCallback(() => {
if (playing) pause();
else void play();
}, [playing, play, pause]);
const setMuted = useCallback(
(m: boolean) => {
if (ref.current) ref.current.muted = m;
setMutedState(m);
},
[ref],
);
const seek = useCallback(
(t: number) => {
if (ref.current) ref.current.currentTime = t;
},
[ref],
);
return { playing, muted, time, duration, play, pause, toggle, setMuted, seek };
}
Copy-paste example
useVideo.example.tsx
'use client';
import { useRef } from 'react';
import { useVideo } from '@/hooks';
export function VideoPlayer() {
const ref = useRef<HTMLVideoElement>(null);
const v = useVideo(ref);
return (
<div>
<video ref={ref} src="/demo.mp4" />
<button onClick={() => void v.play()}>Play</button>
<button onClick={v.pause}>Pause</button>
</div>
);
}Production checklist
- Called only from Client Components or other custom hooks
- Type parameters filled in (e.g.
useFetch<User[]>) - Tip: Always stop tracks on unmount (hooks clean up streams they own).
- Source of truth: open
hooks/media/useVideo.tsfor implementation details