How to build a countdown timer in React

hooks/use-countdown.ts

import { useEffect, useRef, useState } from "react";

type Source = {
  /** Seconds remaining, from the server. */
  remainingSeconds: number;
  /** The server's clock at the moment it produced that number. */
  serverTime: string;
};

/**
 * A countdown that ticks locally but counts against the server.
 *
 * The visitor's clock is measured against the server's once, and
 * the difference is subtracted on every tick. A device that is an
 * hour fast still shows the correct remaining time.
 */
export function useCountdown({ remainingSeconds, serverTime }: Source) {
  const [left, setLeft] = useState(remainingSeconds);

  const skew = useRef(0);
  const endsAt = useRef(0);

  useEffect(() => {
    skew.current = Date.now() - new Date(serverTime).getTime();
    endsAt.current = Date.now() - skew.current + remainingSeconds * 1000;
    setLeft(remainingSeconds);
  }, [remainingSeconds, serverTime]);

  useEffect(() => {
    function tick() {
      const now = Date.now() - skew.current;
      setLeft(Math.max(0, Math.round((endsAt.current - now) / 1000)));
    }

    tick();
    const id = setInterval(tick, 1000);

    // A throttled or restored tab has a stale value. Recompute
    // as soon as it is visible instead of waiting for the interval.
    document.addEventListener("visibilitychange", tick);

    return () => {
      clearInterval(id);
      document.removeEventListener("visibilitychange", tick);
    };
  }, []);

  return {
    seconds: left,
    ended: left === 0,
    days: Math.floor(left / 86400),
    hours: Math.floor((left % 86400) / 3600),
    minutes: Math.floor((left % 3600) / 60),
    remainder: left % 60,
  };
}

hooks/use-timer.ts

import { useEffect, useState } from "react";

/**
 * Reads status through YOUR backend, never the API directly —
 * an API key in frontend JavaScript is a public API key.
 */
export function useTimer(timerId: string, resyncMs = 60_000) {
  const [source, setSource] = useState<Source | null>(null);

  useEffect(() => {
    let cancelled = false;

    async function load() {
      const response = await fetch(`/api/countdown/${timerId}`);
      if (!response.ok) return;
      const data = await response.json();
      if (!cancelled) {
        setSource({
          remainingSeconds: data.remaining_seconds,
          serverTime: data.server_time,
        });
      }
    }

    load();

    // Re-sync occasionally so a long-lived tab cannot drift, and
    // whenever the tab becomes visible again.
    const id = setInterval(load, resyncMs);
    document.addEventListener("visibilitychange", load);

    return () => {
      cancelled = true;
      clearInterval(id);
      document.removeEventListener("visibilitychange", load);
    };
  }, [timerId, resyncMs]);

  return source;
}

components/countdown.tsx

export function Countdown({ timerId }: { timerId: string }) {
  const source = useTimer(timerId);

  // Nothing to count against yet — render a stable placeholder
  // rather than a zero that will visibly jump.
  if (!source) return <span aria-hidden="true">--:--:--</span>;

  return <Clock source={source} />;
}

function Clock({ source }: { source: Source }) {
  const { days, hours, minutes, remainder, ended } = useCountdown(source);

  if (ended) return <p>This offer has closed.</p>;

  return (
    <time
      dateTime={`P${days}DT${hours}H${minutes}M${remainder}S`}
      aria-live="polite"
      aria-atomic="true"
    >
      {days > 0 && <>{days}d </>}
      {String(hours).padStart(2, "0")}:
      {String(minutes).padStart(2, "0")}:
      {String(remainder).padStart(2, "0")}
    </time>
  );
}

Sub-second variant

// If you need sub-second precision — an auction closing, say —
// requestAnimationFrame is smoother than setInterval and pauses
// itself when the tab is hidden.
useEffect(() => {
  let frame: number;

  function loop() {
    const now = Date.now() - skew.current;
    setMs(Math.max(0, endsAt.current - now));
    frame = requestAnimationFrame(loop);
  }

  frame = requestAnimationFrame(loop);
  return () => cancelAnimationFrame(frame);
}, []);

// Only reach for this when the extra precision is visible to a
// user. At one-second granularity setInterval is cheaper.