React Countdown Component

2.3.6 · active · verified Sun Apr 19

react-countdown is a highly customizable React component designed to display countdowns. It is currently stable at version 2.3.6 and has seen active maintenance, with multiple bugfix and minor feature releases within the 2.x series. The library allows developers to define a target date and provides flexible rendering options, including a custom `renderer` function or rendering a child component upon completion. Key features include support for displaying milliseconds with configurable precision, an `overtime` prop to allow negative countdowns, and an API to programmatically `stop`, `isStarted`, and `isStopped` the countdown. It ships with TypeScript types, ensuring type safety for React applications. This package differentiates itself through its extensive customization capabilities and robust API for managing countdown state.

Common errors

```
Property 'date' is missing in type 'CountdownProps' but required in type 'Readonly<CountdownProps>'.
```
cause The `date` prop was made required for the `Countdown` component starting from version 2.3.3.

fix Ensure the `date` prop is always provided, e.g., `<Countdown date={Date.now() + 10000} />`.
```
TypeError: Cannot read properties of undefined (reading 'total') (when trying to show milliseconds)
```
cause Attempting to render `props.total` (milliseconds) in a custom renderer without setting `intervalDelay` and `precision` correctly.

fix Add `intervalDelay={0}` (or a small number like `10`) and `precision={3}` (for 3 decimal places of milliseconds) to the `Countdown` component props.
```
TypeError: Countdown is not a constructor (or similar errors like `_reactCountdown.Countdown is not a function`)
```
cause Incorrectly importing `Countdown` as a named export when it is a default export.

fix Change the import statement from `import { Countdown } from 'react-countdown';` to `import Countdown from 'react-countdown';`.

Warnings

breaking The `date` prop on the `Countdown` component transitioned from being optional to required.
Fix: Always provide the `date` prop to the `Countdown` component. TypeScript users will encounter a compilation error if omitted.
gotcha Displaying milliseconds accurately requires specific `intervalDelay` and `precision` prop configurations.
Fix: To show milliseconds, set `intervalDelay` to a value less than 1000ms (e.g., `0` or `10`) and `precision` to `1`, `2`, or `3`.
gotcha The `onComplete` callback might not consistently trigger immediately if the countdown `date` is already in the past at component initialization in older versions.
Fix: Upgrade to version `2.3.3` or newer, which includes a fix to ensure `onComplete` triggers consistently, even if the countdown is completed on start.
deprecated Internal usage of `React.Props` type was removed due to deprecation within React itself.
Fix: This was an internal fix. Users should ensure their project's React and TypeScript versions are up-to-date and compatible, though this change should not directly impact consumer code unless custom type overrides were in place.

Install

npm install react-countdown npm
yarn add react-countdown yarn
pnpm add react-countdown pnpm

Imports

Countdown

wrong:

import { Countdown } from 'react-countdown';

correct:

import Countdown from 'react-countdown';

The primary component is a default export.

CountdownProps
```
import type { CountdownProps } from 'react-countdown';
```
Type definition for the Countdown component's props.
CountdownRendererFn
```
import type { CountdownRendererFn } from 'react-countdown';
```
Type definition for the custom renderer function.

Quickstart

Demonstrates a basic countdown with a custom renderer and completion callback, using modern React 18+ ReactDOM.createRoot.

import React from 'react';
import ReactDOM from 'react-dom/client';
import Countdown from 'react-countdown';

// Create a root
const root = ReactDOM.createRoot(document.getElementById('root'));

const Completionist = () => <span>Time's up!</span>;

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

root.render(
  <React.StrictMode>
    <Countdown
      date={Date.now() + 10000} // Countdown for 10 seconds
      renderer={renderer}
      onComplete={() => console.log('Countdown finished!')}
    />
  </React.StrictMode>
);

view raw JSON →