react-countdown

When using Server-Side Rendering (SSR), you might see the error "Warning: Text content did not match...". This happens because the server's time and the client's time differ during hydration.

Solutions:

1. Client-only rendering: Only render the countdown after the component has mounted on the client.

const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);

if (!mounted) return null; // or a placeholder
return <Countdown {...props} />;

2. Suppress warning: Use suppressHydrationWarning on the output element.
3. Manual start: Set autoStart={false} and call api.start() via useEffect once the client is ready.

const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
if (!mounted) return null; // render nothing, or your own placeholder, until client-side
return <Countdown {...props} />;

A stopwatch can be implemented by using the Countdown component with the overtime prop enabled and setting the date to the current time (Date.now()).

Because the timer starts at 0, the time delta's total is negative and completed is true from the first tick. However, the formatted values in the render props remain positive, allowing them to function as a count-up timer. You can control the stopwatch using the api object (start(), pause(), stop()).

import { createRoot } from 'react-dom/client';
import Countdown from 'react-countdown';

createRoot(document.getElementById('root')).render(
  <Countdown
    date={Date.now()}
    overtime
    daysInHours
    autoStart={false}
    renderer={({ formatted, api }) => (
      <div>
        <span>
          {formatted.hours}:{formatted.minutes}:{formatted.seconds}
        </span>
        <button onClick={api.start}>{api.isPaused() ? 'Resume' : 'Start'}</button>
        <button onClick={api.pause}>Pause</button>
      </div>
    )}
  />
);

If you prefer using React Hooks instead of the Countdown component, use the useCountdown hook. Pass the configuration object (containing the date) to the hook.

Note: If you are passing a dynamic object, you should wrap it in useRef or set freezeProps to true to prevent unnecessary re-renders.

import { useRef } from 'react';
import { createRoot } from 'react-dom/client';
import { useCountdown } from 'react-countdown';

const MyComponent = () => {
  const props = useRef({ date: Date.now() + 5000 });
  const { hours, minutes, seconds, api } = useCountdown(props.current);
  return <span>{api.isCompleted() ? 'Completionist!' : `${hours}:${minutes}:${seconds}`} </span>;
};

createRoot(document.getElementById('root')).render(<MyComponent />);

import { useRef } from 'react';
import { createRoot } from 'react-dom/client';
import { useCountdown } from 'react-countdown';

// Function component
const MyComponent = () => {
  const props = useRef({ date: Date.now() + 5000 });
  const { hours, minutes, seconds, api } = useCountdown(props.current);
  return <span>{api.isCompleted() ? 'Completionist!' : `${hours}:${minutes}:${seconds}`} </span>;
};

createRoot(document.getElementById('root')).render(<MyComponent />);

You can customize the visual output of the countdown or signal completion using the renderer prop and the onComplete callback.

The renderer prop accepts a function that receives an object containing time units (hours, minutes, seconds, etc.) and a completed boolean. This allows you to return different UI elements based on whether the countdown has finished.

import { createRoot } from 'react-dom/client';
import Countdown from 'react-countdown';

const Completionist = () => <span>You are good to go!</span>;

const renderer = ({ hours, minutes, seconds, completed }) => {
  return completed ? (
    <Completionist />
  ) : (
    <span>{hours}:{minutes}:{seconds}</span>
  );
};

createRoot(document.getElementById('root')).render(
  <Countdown date={Date.now() + 5000} renderer={renderer} />
);

import { createRoot } from 'react-dom/client';
import Countdown from 'react-countdown';

// Random component
const Completionist = () => <span>You are good to go!</span>;

// Renderer callback with completed condition
const renderer = ({ hours, minutes, seconds, completed }) => {
  return completed ? (
    <Completionist />
  ) : (
    <span>
      {hours}:{minutes}:{seconds}
    </span>
  );
};

createRoot(document.getElementById('root')).render(
  <Countdown date={Date.now() + 5000} renderer={renderer} />
);

The <Countdown /> component accepts several optional lifecycle callbacks as props. These allow you to trigger side effects at specific stages of the countdown's lifecycle. Most callbacks receive a time delta object as their first argument.

• onMount: Triggered when the component mounts.
• onStart: Triggered whenever the countdown starts (including the first run).
• onPause: Triggered every time the countdown is paused.
• onStop: Triggered every time the countdown is stopped.
• onTick: Triggered at every interval (defined by intervalDelay). Note: This only fires when controlled={false}. It fires for the final tick where completed: true is passed in the delta object.
• onComplete: Triggered when the countdown ends. Unlike onTick, this works even if controlled={true}. It receives the time delta object as the first argument and a boolean as the second argument (indicating if it transitioned into the completed state or completed immediately on start).