React Awesome Countdown Timer

A modern, customizable countdown timer component for React with custom renderer, callbacks, and zero dependencies.

Live Demo

✨ Features

• 🎯 Modern React with hooks
• 🎨 Fully customizable (CSS classes + inline styles)
• 🎭 Custom renderer with render props
• 🔔 Lifecycle callbacks (onComplete, onTick, onStart, onPause, onStop, onMount)
• 🎮 Imperative API (start, pause, stop)
• 👶 Completion children
• 📦 Zero dependencies
• ⚡ Lightweight (~1.6KB gzipped)
• 🔧 TypeScript ready

📦 Installation

npm install react-awesome-countdowntimer
# or
pnpm add react-awesome-countdowntimer
# or
yarn add react-awesome-countdowntimer

🚀 Quick Start

import CountdownTimer from 'react-awesome-countdowntimer';
import 'react-awesome-countdowntimer/dist/index.css';

function App() {
  const endDate = new Date('2026-12-31T23:59:59');
  return <CountdownTimer endDate={endDate} />;
}

📖 Examples

Custom Styling

// With CSS classes
<CountdownTimer 
  endDate={endDate}
  timerClassName="my-timer"
  sectionClassName="my-section"
/>

// With inline styles
<CountdownTimer 
  endDate={endDate}
  timerStyle={{ background: '#f0f4f8', padding: '30px' }}
  sectionStyle={{ background: '#3b82f6', borderRadius: '12px' }}
/>

Custom Renderer

<CountdownTimer 
  endDate={endDate}
  renderer={({ days, hours, minutes, seconds, completed }) => {
    if (completed) return <div>🎉 Time's up!</div>;
    return <div>{days}d {hours}:{minutes}:{seconds}</div>;
  }}
/>

Callbacks

<CountdownTimer 
  endDate={endDate}
  onComplete={() => console.log('Done!')}
  onTick={(delta) => console.log(delta.seconds)}
/>

Completion Children

<CountdownTimer endDate={endDate}>
  <div>✨ Complete! ✨</div>
</CountdownTimer>

Imperative Control

const timerRef = useRef();

<CountdownTimer ref={timerRef} endDate={endDate} autoStart={false} />
<button onClick={() => timerRef.current.start()}>Start</button>
<button onClick={() => timerRef.current.pause()}>Pause</button>

Advanced Features

// Overtime mode (continue past zero)
<CountdownTimer endDate={endDate} overtime={true} />

// Days in hours (show 48h instead of 2d)
<CountdownTimer endDate={endDate} daysInHours={true} />

// Custom padding
<CountdownTimer endDate={endDate} zeroPadTime={3} /> // 001:002:003

🎛️ API Reference

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | endDate | Date | required | Target date/time | | renderer | function | - | Custom render function | | children | ReactNode | - | Content shown when complete | | onComplete | function | - | Callback when finished | | onTick | function | - | Callback every second | | onStart | function | - | Callback when started | | onPause | function | - | Callback when paused | | onStop | function | - | Callback when stopped | | onMount | function | - | Callback on mount | | autoStart | boolean | true | Auto-start countdown | | zeroPadTime | number | 2 | Zero-padding digits (1-3) | | overtime | boolean | false | Continue past zero | | daysInHours | boolean | false | Show hours instead of days | | timerClassName | string | '' | Timer container class | | sectionClassName | string | '' | Section class | | timeClassName | string | '' | Time number class | | labelClassName | string | '' | Label class | | timerStyle | object | - | Timer container styles | | sectionStyle | object | - | Section styles | | timeStyle | object | - | Time number styles | | labelStyle | object | - | Label styles |

Render Props

The renderer function receives:

{
  total: number;      // Milliseconds remaining
  days: number;       // Days remaining
  hours: number;      // Hours remaining
  minutes: number;    // Minutes remaining
  seconds: number;    // Seconds remaining
  completed: boolean; // Is complete
  formatted: {        // Zero-padded strings
    days: string;
    hours: string;
    minutes: string;
    seconds: string;
  }
}

Imperative API

const ref = useRef();
ref.current.start();      // Start countdown
ref.current.pause();      // Pause countdown
ref.current.stop();       // Stop countdown
ref.current.isPaused();   // Returns boolean
ref.current.isStopped();  // Returns boolean
ref.current.isCompleted(); // Returns boolean

Default CSS Classes

• .react-countdown-timer - Main container
• .react-countdown-section - Time unit box
• .react-countdown-time - Number display
• .react-countdown-label - Label text

📄 License

MIT © Hassan Tauqeer

⭐ Support

Give a ⭐️ if this project helped you!