Full Countdown for Next.js

A comprehensive and highly optimized countdown timer hook for Next.js applications with TypeScript support.

Features

• ⏱️ Normal countdown with seconds, minutes, hours, days, weeks, months, and years
• 📅 Date-based countdown (count down to a specific date)
• 🎛️ Complete timer controls: start, pause, stop, restart
• 📊 Multiple formatting options (standard, compact, verbose, custom)
• 🌐 Internationalization support for labels
• ⚡ Highly optimized with zero performance issues
• 📱 TypeScript support

Installation

npm install full-countdown-nextjs
# or
yarn add full-countdown-nextjs

Basic Usage

import { useCountdown } from "full-countdown-nextjs";

function MyComponent() {
  const countdown = useCountdown({
    initialValue: 60, // 60 seconds
    autoStart: true,
  });

  return (
    <div>
      <p>Time remaining: {countdown.formatted.standard}</p>
      <button onClick={countdown.pause}>Pause</button>
      <button onClick={countdown.start}>Start</button>
      <button onClick={countdown.restart}>Restart</button>
    </div>
  );
}

Date-based Countdown

import { useCountdown } from "full-countdown-nextjs";

function EventCountdown() {
  const eventDate = new Date("2025-12-31T23:59:59");

  const countdown = useCountdown({
    targetDate: eventDate,
    autoStart: true,
  });

  return (
    <div>
      <h2>New Year's Countdown</h2>
      <p>{countdown.formatted.verbose}</p>
    </div>
  );
}

Internationalization

import { useCountdown } from "full-countdown-nextjs";

function SpanishCountdown() {
  const spanishLabels = {
    seconds: "segundos",
    minutes: "minutos",
    hours: "horas",
    days: "días",
    weeks: "semanas",
    months: "meses",
    years: "años",
    // Short versions
    secondsShort: "s",
    minutesShort: "m",
    hoursShort: "h",
    daysShort: "d",
    weeksShort: "sem",
    monthsShort: "mes",
    yearsShort: "a",
  };

  const countdown = useCountdown({
    initialValue: 3600, // 1 hour
    labels: spanishLabels,
    autoStart: true,
  });

  return (
    <div>
      <p>{countdown.formatted.verbose}</p>
    </div>
  );
}

Custom Formatting

import { useCountdown } from "full-countdown-nextjs";

function CustomFormattedCountdown() {
  const countdown = useCountdown({
    initialValue: 3661, // 1 hour, 1 minute, 1 second
    autoStart: true,
  });

  return (
    <div>
      <p>Standard: {countdown.formatted.standard}</p> {/* 01:01:01 */}
      <p>Compact: {countdown.formatted.compact}</p> {/* 1h 1m 1s */}
      <p>Verbose: {countdown.formatted.verbose}</p>{" "}
      {/* 1 hour, 1 minute, and 1 second */}
      <p>
        Custom: {countdown.formatted.custom("%H hours, %m minutes, %s seconds")}
      </p> {/* 01 hours, 01 minutes, 01 seconds */}
      <p>
        Custom with days: {countdown.formatted.custom("%D days %H:%m:%s")}
      </p>{" "}
      {/* 0 days 01:01:01 */}
    </div>
  );
}

API Reference

useCountdown Options

| Option | Type | Default | Description | | ---------------- | ----------------- | --------------- | ----------------------------------------------------- | | initialValue | number | 0 | Initial countdown time in seconds | | targetDate | Date | undefined | Target date to count down to (overrides initialValue) | | autoStart | boolean | true | Whether to start the timer automatically | | onComplete | () => void | undefined | Callback function when countdown completes | | updateInterval | number | 1000 | Update interval in milliseconds | | labels | CountdownLabels | defaultLabels | Custom labels for time units |

Return Value

The hook returns an object with the following properties:

| Property | Type | Description | | ------------ | ----------------------------- | ----------------------------------------------- | | values | CountdownValues | Raw time values (seconds, minutes, hours, etc.) | | formatted | FormattedValues | Pre-formatted time strings | | isRunning | boolean | Whether the countdown is currently running | | isComplete | boolean | Whether the countdown has completed | | start | () => void | Start the countdown | | pause | () => void | Pause the countdown | | stop | () => void | Stop the countdown and reset to initial value | | restart | (newValue?: number) => void | Restart with optional new value | | setTime | (seconds: number) => void | Set a new time value |

CountdownValues

The values object contains the following properties:

| Property | Type | Description | | --------- | -------- | ----------------------- | | total | number | Total remaining seconds | | seconds | number | Seconds part (0-59) | | minutes | number | Minutes part (0-59) | | hours | number | Hours part (0-23) | | days | number | Days part | | weeks | number | Weeks part | | months | number | Months part | | years | number | Years part |

FormattedValues

The formatted object contains the following properties:

| Property | Type | Description | | ---------- | ------------------------------ | ----------------------------------------------------- | | standard | string | Standard format (MM:SS or HH:MM:SS) | | compact | string | Compact format (1d 2h 3m 4s) | | verbose | string | Verbose format (1 day, 2 hours, 3 minutes, 4 seconds) | | custom | (template: string) => string | Custom format based on provided template |

Custom Format Placeholders

The custom formatter supports the following placeholders:

| Placeholder | Description | | ----------- | --------------------- | | %Y | Years | | %M | Months | | %W | Weeks | | %D | Days | | %H | Hours (zero-padded) | | %m | Minutes (zero-padded) | | %s | Seconds (zero-padded) | | %t | Total seconds |

Performance Optimization

This countdown hook is optimized for performance in several ways:

1. Uses useRef to avoid unnecessary re-renders
2. Stores calculation-heavy values in refs
3. Uses useCallback for memoized functions
4. Properly cleans up intervals on unmount
5. Updates only when necessary

Examples

Check out the examples folder for more usage examples:

• BasicCountdown.tsx: Simple countdown timer with controls
• DateCountdown.tsx: Date-based countdown example
• NextJsExample.tsx: Full-featured example with internationalization

License

MIT