MediaAdvancedSSR-safehooks/media/useVideo.ts

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 · useVideo
Editor
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.ts for implementation details