Mantine Clock

Undolog

@gfazioli/mantine-clock

React Clock components and hooks for Mantine with timezone support, countdown timers, customization options, and real-time updates.

Installation

yarn add @gfazioli/mantine-clock

After installation import package styles at the root of your application:

import '@gfazioli/mantine-clock/styles.css';

You can import styles within a layer @layer mantine-clock by importing @gfazioli/mantine-clock/styles.layer.css file.

import '@gfazioli/mantine-clock/styles.layer.css';

Usage

The Clock component displays a clock with customizable hands, ticks, and numbers.

12

3

6

9

1

2

4

5

7

8

10

11

Size
Color
Hour ticks color
Hour ticks opacity
Minute ticks color
Minute ticks opacity
import { Clock } from '@gfazioli/mantine-clock';

function Demo() {
  return (
    <Clock color="" />
  );
}

Static Clock with Value

The Clock component can display a static time using the value prop. When running is set to false, the clock will show the specified time without animation. If no value is provided, it displays the current time. The value prop accepts time strings in various formats or Date objects.

12

3

6

9

1

2

4

5

7

8

10

11

Default Static
(Current Time)

12

3

6

9

1

2

4

5

7

8

10

11

Static Time
15:30

12

3

6

9

1

2

4

5

7

8

10

11

With Seconds
09:45:30

12

3

6

9

1

2

4

5

7

8

10

11

Date Object
11:25:15

import { Clock } from '@gfazioli/mantine-clock';
import { Group, Stack, Text } from '@mantine/core';

function Demo() {
  return (
    <Group justify="center" gap="xl">
      <Stack align="center" gap="sm">
        <Clock 
          running={false} 
          size={200}
          primaryNumbersProps={{ c: 'gray.6', fw: 600 }}
        />
        <Text size="sm" c="dimmed" ta="center">
          Default Static
          <br />
          (Current Time)
        </Text>
      </Stack>

      <Stack align="center" gap="sm">
        <Clock 
          running={false} 
          value="15:30" 
          size={200}
          primaryNumbersProps={{ c: 'blue.6', fw: 600 }}
        />
        <Text size="sm" c="dimmed" ta="center">
          Static Time
          <br />
          15:30
        </Text>
      </Stack>

      <Stack align="center" gap="sm">
        <Clock 
          running={false} 
          value="09:45:30" 
          size={200}
          primaryNumbersProps={{ c: 'red.6', fw: 600 }}
          secondHandColor="red.6"
        />
        <Text size="sm" c="dimmed" ta="center">
          With Seconds
          <br />
          09:45:30
        </Text>
      </Stack>

      <Stack align="center" gap="sm">
        <Clock 
          running={false} 
          value={new Date(2024, 0, 1, 11, 25, 15)} 
          size={200}
          primaryNumbersProps={{ c: 'teal.6', fw: 600 }}
        />
        <Text size="sm" c="dimmed" ta="center">
          Date Object
          <br />
          11:25:15
        </Text>
      </Stack>
    </Group>
  );
}

Reverse Countdown Clock

This demo showcases how to create a reverse countdown clock by combining the Clock component with the useClockCountDown hook. The clock displays the remaining time visually as it counts down, creating a unique reverse clock effect. The clock hands move backwards as time decreases, and the appearance changes when the countdown is completed.

12

3

6

9

1

2

4

5

7

8

10

11

Reverse Clock
Counting Down

Countdown Settings

00:00:00

Status: Paused

import { useState } from 'react';
import { Clock, useClockCountDown } from '@gfazioli/mantine-clock';
import { Button, Group, NumberInput, Paper, Stack, Text } from '@mantine/core';

function Demo() {
  const [hours, setHours] = useState(2);
  const [minutes, setMinutes] = useState(30);
  const [seconds, setSeconds] = useState(0);

  const countdown = useClockCountDown({
    enabled: false, // Start paused
    hours,
    minutes,
    seconds,
    padHours: true,
    padMinutes: true,
    padSeconds: true,
    onCountDownCompleted: () => {
      console.log('Countdown completed!');
    },
  });

  // Format the countdown time for the Clock component
  const countdownValue = `${countdown.hours}:${countdown.minutes}:${countdown.seconds}`;

  return (
    <Paper p="md" withBorder>
      <Group align="flex-start" gap="xl">
        {/* Clock showing countdown time */}
        <Stack align="center" gap="md">
          <Clock
            value={countdownValue}
            running={false}
            size={300}
            primaryNumbersProps={{ c: countdown.isCompleted ? 'red.6' : 'blue.6', fw: 600 }}
            secondHandColor={countdown.isCompleted ? 'red.6' : 'blue.6'}
            minuteHandColor={countdown.isCompleted ? 'red.6' : 'blue.6'}
            hourHandColor={countdown.isCompleted ? 'red.6' : 'blue.6'}
          />
          <Text size="sm" c="dimmed" ta="center">
            Reverse Clock
            <br />
            {countdown.isCompleted ? 'Time Up!' : 'Counting Down'}
          </Text>
        </Stack>

        {/* Controls */}
        <Stack gap="md" flex={1}>
          <Title order={4}>Countdown Settings</Title>
          
          <Group gap="md">
            <NumberInput
              label="Hours"
              value={hours}
              onChange={(value) => setHours(Number(value) || 0)}
              min={0}
              max={23}
              w={80}
            />
            <NumberInput
              label="Minutes"
              value={minutes}
              onChange={(value) => setMinutes(Number(value) || 0)}
              min={0}
              max={59}
              w={80}
            />
            <NumberInput
              label="Seconds"
              value={seconds}
              onChange={(value) => setSeconds(Number(value) || 0)}
              min={0}
              max={59}
              w={80}
            />
          </Group>

          <Text fw={700} size="lg" ta="center" 
                c={countdown.isCompleted ? 'red' : countdown.totalMilliseconds < 10000 ? 'orange' : undefined}>
            {countdown.hours}:{countdown.minutes}:{countdown.seconds}
          </Text>
          
          <Text size="sm" c="dimmed" ta="center">
            Status: {countdown.isCompleted ? 'Completed!' : countdown.isRunning ? 'Running...' : 'Paused'}
          </Text>

          <Group justify="center" gap="sm">
            <Button 
              onClick={countdown.start} 
              disabled={countdown.isRunning || countdown.isCompleted}
              variant="filled"
            >
              Start
            </Button>
            <Button 
              onClick={countdown.pause} 
              disabled={!countdown.isRunning}
              variant="outline"
            >
              Pause
            </Button>
            <Button 
              onClick={countdown.resume} 
              disabled={countdown.isRunning || countdown.isCompleted}
              variant="outline"
            >
              Resume
            </Button>
            <Button 
              onClick={countdown.reset}
              variant="light"
            >
              Reset
            </Button>
          </Group>
        </Stack>
      </Group>
    </Paper>
  );
}

Running Clock with Initial Value

You can also set an initial time value for a running clock. The clock will start from the specified time and continue running in real time.

12

3

6

9

1

2

4

5

7

8

10

11

Starts at 08:00
(smooth animation)

12

3

6

9

1

2

4

5

7

8

10

11

Starts at 14:30:45
(tick animation)

12

3

6

9

1

2

4

5

7

8

10

11

From Date Object
(half-tick animation)

import { Clock } from '@gfazioli/mantine-clock';
import { Group, Stack, Text } from '@mantine/core';

function Demo() {
  return (
    <Group justify="center" gap="xl">
      <Stack align="center" gap="sm">
        <Clock 
          value="08:00:00" 
          size={200}
          secondHandBehavior="smooth"
          primaryNumbersProps={{ c: 'green.6', fw: 600 }}
        />
        <Text size="sm" c="dimmed" ta="center">
          Starts at 08:00
          <br />
          (smooth animation)
        </Text>
      </Stack>

      <Stack align="center" gap="sm">
        <Clock 
          value="14:30:45" 
          size={200}
          secondHandBehavior="tick"
          primaryNumbersProps={{ c: 'violet.6', fw: 600 }}
          secondHandColor="violet.6"
        />
        <Text size="sm" c="dimmed" ta="center">
          Starts at 14:30:45
          <br />
          (tick animation)
        </Text>
      </Stack>

      <Stack align="center" gap="sm">
        <Clock 
          value={new Date(2024, 0, 1, 16, 15, 30)} 
          size={200}
          secondHandBehavior="tick-half"
          primaryNumbersProps={{ c: 'orange.6', fw: 600 }}
        />
        <Text size="sm" c="dimmed" ta="center">
          From Date Object
          <br />
          (half-tick animation)
        </Text>
      </Stack>
    </Group>
  );
}

Clock Hands

The Clock component allows you to customize the appearance of the clock hands. You can set the color, size, and other properties of the hour, minute, and second hands.

12

3

6

9

1

2

4

5

7

8

10

11

Second hand color
Second hand opacity
Second hand length
Second hand size
Minute hand color
Minute hand opacity
Minute hand size
Minute hand length
Hour hand color
Hour hand opacity
Hour hand size
Hour hand length
import { Clock } from '@gfazioli/mantine-clock';

function Demo() {
  return (
    <Clock secondHandColor="" minuteHandColor="" hourHandColor="" />
  );
}

Clock Numbers

The Clock component can display numbers on the clock face. You can customize the font size, color, and visibility of the numbers.

12

3

6

9

1

2

4

5

7

8

10

11

Hour numbers distance
Primary numbers color
Primary numbers opacity
Secondary numbers color
Secondary numbers opacity
import { Clock } from '@gfazioli/mantine-clock';

function Demo() {
  return (
    <Clock primaryNumbersColor="" secondaryNumbersColor="" />
  );
}

Clock Number Fonts

The Clock component supports custom fonts for the numbers displayed on the clock face. You can choose from various font styles to match your design preferences.

12

3

6

9

1

2

4

5

7

8

10

11

import { Clock } from '@gfazioli/mantine-clock';

function Demo() {
  return (
    <Clock
      primaryNumbersColor="blue"
      primaryNumbersProps={{
        ff: 'monospace',
        fw: 900,
        fz: 32,
      }}
      secondaryNumbersColor="gray"
      secondaryNumbersProps={{
        ff: 'monospace',
        fw: 500,
        fz: 16,
      }}
      styles={{
        primaryNumber: {
          textShadow: '0 4px 6px rgba(0, 0, 0, 0.3)',
        },
      }}
    />
  );
}

Styling with ClassNames

The Clock component supports extensive customization through the classNames prop, allowing you to style every part of the clock using CSS modules or custom CSS classes. This approach gives you complete control over the clock's appearance.

Available ClassNames

The Clock component exposes the following classNames for styling:

  • root - Root element of the clock component
  • clockContainer - Main clock container
  • glassWrapper - Glass wrapper with shadow effects
  • clockFace - Clock face containing all visual elements
  • hourMarks - Container for hour marks and numbers
  • hourTick - Hour tick marks (12 positions)
  • minuteTick - Minute tick marks (60 positions, excluding hour positions)
  • number - Base styles for hour numbers (1-12)
  • primaryNumber - Primary hour numbers (12, 3, 6, 9)
  • secondaryNumber - Secondary hour numbers (1, 2, 4, 5, 7, 8, 10, 11)
  • hand - Base styles for clock hands
  • hourHand - Hour hand specific styles
  • minuteHand - Minute hand specific styles
  • secondHandContainer - Container for second hand and counterweight
  • secondHand - Second hand specific styles
  • secondHandCounterweight - Second hand counterweight
  • centerBlur - Center blur effect
  • centerDot - Center dot at the pivot point

Neon Theme Example

The following example demonstrates a complete custom theme using CSS modules with neon effects, animations, and modern styling techniques:

Neon Cyber Clock Theme

Custom styling using CSS modules and classNames prop

12

3

6

9

1

2

4

5

7

8

10

11

import { Clock } from '@gfazioli/mantine-clock';
import { Stack, Text, Title } from '@mantine/core';
import classes from './Clock.demo.classNames.module.css';

function Demo() {
  return (
    <Stack align="center" justify="center">
      <Title order={4} ta="center" mb="xs">
        Neon Cyber Clock Theme
      </Title>
      <Text size="sm" c="dimmed" ta="center" mb="md">
        Custom styling using CSS modules and classNames prop
      </Text>
      <Clock
        size={200}
        secondHandBehavior="smooth"
        classNames={{
          glassWrapper: classes.glassWrapper,
          clockFace: classes.clockFace,
          hourTick: classes.hourTick,
          minuteTick: classes.minuteTick,
          primaryNumber: classes.primaryNumber,
          secondaryNumber: classes.secondaryNumber,
          hourHand: classes.hourHand,
          minuteHand: classes.minuteHand,
          secondHand: classes.secondHand,
          secondHandCounterweight: classes.secondHandCounterweight,
          centerDot: classes.centerDot,
          centerBlur: classes.centerBlur,
        }}
      />
    </Stack>
  );
}

Timezone Support

The Clock component supports displaying time in different timezones around the world. Use the timezone prop to specify a timezone string, allowing you to create world clocks or display time for specific regions.

12

3

6

9

1

2

4

5

7

8

10

11

import { Clock } from '@gfazioli/mantine-clock';

function Demo() {
  return (
    <Clock timezone="UTC" />
  );
}

World Clocks Example

Here's an example showing multiple clocks displaying time in different regions simultaneously:

12

3

6

9

1

2

4

5

7

8

10

11

New York

12

3

6

9

1

2

4

5

7

8

10

11

London

12

3

6

9

1

2

4

5

7

8

10

11

Tokyo

import { Clock } from '@gfazioli/mantine-clock';
import { Group, Stack, Text } from '@mantine/core';

// This demo showcases the usage of the Clock component from the @gfazioli/mantine-clock package.
// It displays world clocks for different timezones, allowing users to see the current time in various locations.

function Demo() {
  return (
    <Group grow>
      <Stack align="center">
        <Clock timezone="America/New_York" size={200} />
        <Text fw={600} c="dimmed">
          New York
        </Text>
      </Stack>

      <Stack align="center">
        <Clock timezone="Europe/London" size={200} />
        <Text fw={600} c="dimmed">
          London
        </Text>
      </Stack>

      <Stack align="center">
        <Clock timezone="Asia/Tokyo" size={200} />
        <Text fw={600} c="dimmed">
          Tokyo
        </Text>
      </Stack>
    </Group>
  );
}

Supported Timezones

The timezone prop accepts any valid IANA timezone identifier. Some common examples include:

  • UTC: 'UTC' - Coordinated Universal Time
  • Americas: 'America/New_York', 'America/Los_Angeles', 'America/Chicago', 'America/Toronto'
  • Europe: 'Europe/London', 'Europe/Berlin', 'Europe/Paris', 'Europe/Rome'
  • Asia: 'Asia/Tokyo', 'Asia/Shanghai', 'Asia/Singapore', 'Asia/Dubai'
  • Oceania: 'Australia/Sydney', 'Australia/Melbourne', 'Pacific/Auckland'

When no timezone is specified, the clock displays the local time of the user's system.

Usage Examples

import { Clock } from '@gfazioli/mantine-clock';

function Demo() {
  return (
    <div>
      {/* Display Tokyo time */}
      <Clock timezone="Asia/Tokyo" />

      {/* Display New York time */}
      <Clock timezone="America/New_York" />

      {/* Display UTC time */}
      <Clock timezone="UTC" />

      {/* Display local time (default) */}
      <Clock />
    </div>
  );
}

Hooks

useClock Hook

The useClock hook provides real-time clock data with support for timezones, formatting options, and update frequency control. This hook is perfect for creating digital clocks, displaying time information, or building custom time-based components.

Digital Clock with Controls

00:00:00

1/1/2024 - Week 1

Status: Paused | Timezone: Europe/Rome | Leap Year: No

Milliseconds: 0

import { useClock } from '@gfazioli/mantine-clock';

function Demo() {
  const clock = useClock({
    enabled: false, // Start paused
    timezone: 'Europe/Rome',
    use24Hours: true,
    padHours: true,
    padMinutes: true,
    padSeconds: true,
    updateFrequency: 1000,
  });

  return (
    <Paper p="md" withBorder>
      <Title order={4} mb="xs">Digital Clock with Controls</Title>
      <Text fw={700} size="xl" mb="xs">
        {clock.hours}:{clock.minutes}:{clock.seconds}
      </Text>
      <Text size="sm" c="dimmed" mb="xs">
        {clock.day}/{clock.month}/{clock.year} - Week {clock.week}
      </Text>
      <Text size="xs" c="dimmed" mb="sm">
        Status: {clock.isRunning ? 'Running' : 'Paused'} | Leap Year: {clock.isLeap ? 'Yes' : 'No'}
      </Text>
      
      <Group gap="xs">
        <Button size="xs" onClick={clock.start} disabled={clock.isRunning}>
          Start
        </Button>
        <Button size="xs" onClick={clock.pause} disabled={!clock.isRunning} variant="outline">
          Pause
        </Button>
        <Button size="xs" onClick={clock.resume} disabled={clock.isRunning} variant="light">
          Resume
        </Button>
        <Button size="xs" onClick={clock.reset} variant="subtle">
          Reset
        </Button>
      </Group>
    </Paper>
  );
}

World Clocks with useClock

You can use multiple instances of the useClock hook to display time in different timezones simultaneously:

New York

00:00:00 AM

1/1/2024

London

00:00:00 AM

1/1/2024

Tokyo

00:00:00 AM

1/1/2024

Sydney

00:00:00 AM

1/1/2024

import { useClock } from '@gfazioli/mantine-clock';

function Demo() {
  
  const newYork = useClock({ 
    timezone: 'America/New_York', 
    use24Hours: false,
    padHours: true,
    padMinutes: true,
    padSeconds: true,
  });
  const london = useClock({ 
    timezone: 'Europe/London', 
    use24Hours: false,
    padHours: true,
    padMinutes: true,
    padSeconds: true,
  });
  const tokyo = useClock({ 
    timezone: 'Asia/Tokyo', 
    use24Hours: false,
    padHours: true,
    padMinutes: true,
    padSeconds: true,
  });
  const sydney = useClock({ 
    timezone: 'Australia/Sydney', 
    use24Hours: false,
    padHours: true,
    padMinutes: true,
    padSeconds: true,
  });

  const ClockCard = ({ clock, city }: { clock: any; city: string }) => (
    <Paper p="md" withBorder style={{ textAlign: 'center' }}>
      <Title order={5} mb="xs">{city}</Title>
      <Text fw={700} size="lg">
        {clock.hours}:{clock.minutes}:{clock.seconds} {clock.amPm}
      </Text>
      <Text size="sm" c="dimmed">
        {clock.day}/{clock.month}/{clock.year}
      </Text>
    </Paper>
  );

  return (
    <Stack gap="md">
      <Group gap="md" grow>
        <ClockCard clock={newYork} city="New York" />
        <ClockCard clock={london} city="London" />
        <ClockCard clock={tokyo} city="Tokyo" />
        <ClockCard clock={sydney} city="Sydney" />
      </Group>
    </Stack>
  );
}

useClock API

The useClock hook accepts the following options:

NameTypeDescription
enabledboolean

Whether the clock is active and updating

timezonestring

The timezone to use for the clock

updateFrequencynumber

The frequency (in milliseconds) at which the clock updates

use24Hoursboolean

Whether to use 24-hour format or 12-hour format

padSecondsboolean

Whether to pad single-digit seconds with a leading zero

padMinutesboolean

Whether to pad single-digit minutes with a leading zero

padHoursboolean

Whether to pad single-digit hours with a leading zero

The hook returns an object with the following properties:

NameTypeDescription
year *number

The current year

month *number

The current month (1-12)

day *number

The current day of the month

week *number

The current week of the year

isLeap *boolean

Whether the current year is a leap year

hours *number | string

The current hour (adjusted for 12/24-hour format)

minutes *number | string

The current minute

seconds *number | string

The current second

milliseconds *number

The current millisecond

amPm *'AM' | 'PM' | undefined

Whether the time is AM or PM (only when use24Hours is false)

isRunning *boolean

Whether the clock is currently running and updating

start *function

Function to start the clock

pause *function

Function to pause the clock

resume *function

Function to resume a paused clock

reset *function

Function to reset the clock to its initial state

useClockCountDown Hook

The useClockCountDown hook provides real-time countdown functionality with support for target dates, duration-based countdowns, and completion callbacks. Perfect for creating countdown timers, event countdowns, or deadline trackers.

Interactive Countdown Timer

00:00:00

Status: Paused

Total milliseconds: 0

import { useClockCountDown } from '@gfazioli/mantine-clock';
import { useState } from 'react';

function Demo() {
  const [hours, setHours] = useState(0);
  const [minutes, setMinutes] = useState(1);
  const [seconds, setSeconds] = useState(0);

  const countdown = useClockCountDown({
    enabled: false, // Start paused
    hours,
    minutes,
    seconds,
    padHours: true,
    padMinutes: true,
    padSeconds: true,
    onCountDownCompleted: () => {
      console.log('Countdown completed!');
      alert('Time\'s up!');
    },
  });

  return (
    <Paper p="md" withBorder>
      <Title order={4} mb="md">Countdown Timer</Title>
      
      <Text fw={700} size="xl" ta="center" mb="md" 
            c={countdown.isCompleted ? 'red' : countdown.totalMilliseconds < 10000 ? 'orange' : undefined}>
        {countdown.hours}:{countdown.minutes}:{countdown.seconds}
      </Text>
      
      <Text size="sm" c="dimmed" ta="center" mb="md">
        Status: {countdown.isCompleted ? 'Completed!' : countdown.isRunning ? 'Running...' : 'Paused'}
      </Text>
      
      <Group gap="xs" justify="center">
        <Button onClick={countdown.start} disabled={countdown.isRunning || countdown.isCompleted}>
          Start
        </Button>
        <Button onClick={countdown.pause} disabled={!countdown.isRunning} variant="outline">
          Pause
        </Button>
        <Button onClick={countdown.resume} disabled={countdown.isRunning || countdown.isCompleted} variant="light">
          Resume
        </Button>
        <Button onClick={countdown.reset} variant="subtle">
          Reset
        </Button>
      </Group>
    </Paper>
  );
}

Countdown to Specific Dates

You can create countdowns to specific target dates using the targetDate option:

🎊 New Year 2026

0d 00:00:00

1 months, 0 days

🎃 Halloween 2025

0d 00:00:00

1 months, 0 days

import { useClockCountDown } from '@gfazioli/mantine-clock';

function Demo() {
  // Countdown to New Year 2026
  const newYear = useClockCountDown({
    enabled: false,
    targetDate: '2026-01-01T00:00:00Z',
    timezone: 'UTC',
    padHours: true,
    padMinutes: true,
    padSeconds: true,
  });

  // Halloween countdown (October 31, 2025)
  const halloween = useClockCountDown({
    enabled: false,
    targetDate: '2025-10-31T00:00:00Z',
    timezone: 'Europe/Rome',
    padHours: true,
    padMinutes: true,
    padSeconds: true,
  });

  const CountdownCard = ({ 
    countdown, 
    title, 
    emoji 
  }: { 
    countdown: any; 
    title: string; 
    emoji: string;
  }) => (
    <Paper p="md" withBorder style={{ textAlign: 'center' }}>
      <Title order={5} mb="xs">{emoji} {title}</Title>
      {countdown.isCompleted ? (
        <Text fw={700} size="lg" c="green">
          🎉 Event has arrived! 🎉
        </Text>
      ) : (
        <>
          <Text fw={700} size="lg" mb="xs">
            {countdown.day}d {countdown.hours}:{countdown.minutes}:{countdown.seconds}
          </Text>
          <Text size="sm" c="dimmed">
            {countdown.month} months, {countdown.day} days
          </Text>
        </>
      )}
    </Paper>
  );

  const allStopped = !newYear.isRunning && !halloween.isRunning;
  const allCompleted = newYear.isCompleted && halloween.isCompleted;

  return (
    <Stack gap="md">
      <Button 
        onClick={() => {
          if (allStopped) {
            newYear.start();
            halloween.start();
          } else {
            newYear.pause();
            halloween.pause();
          }
        }}
        variant={allStopped ? 'outline' : 'filled'}
        disabled={allCompleted}
      >
        {allStopped ? 'Start Countdowns' : 'Stop Countdowns'}
      </Button>
      
      <Group gap="md" grow>
        <CountdownCard countdown={newYear} title="New Year 2026" emoji="🎊" />
        <CountdownCard countdown={halloween} title="Halloween 2025" emoji="🎃" />
      </Group>
    </Stack>
  );
}

useClockCountDown API

The useClockCountDown hook accepts the following options:

NameTypeDescription
enabledboolean

Whether the countdown is active and updating

timezonestring

The timezone to use for countdown calculations

updateFrequencynumber

The frequency (in milliseconds) at which the countdown updates

use24Hoursboolean

Whether to use 24-hour format or 12-hour format

padSecondsboolean

Whether to pad single-digit seconds with a leading zero

padMinutesboolean

Whether to pad single-digit minutes with a leading zero

padHoursboolean

Whether to pad single-digit hours with a leading zero

targetDateDate | string

Target date for the countdown (Date object or ISO string)

hoursnumber

Number of hours to count down from current time

minutesnumber

Number of minutes to count down from current time

secondsnumber

Number of seconds to count down from current time

onCountDownCompletedfunction

Callback function called when countdown reaches zero

The hook returns an object with the following properties:

NameTypeDescription
year *number

The remaining years

month *number

The remaining months (1-12)

day *number

The remaining days

week *number

The remaining weeks

isLeap *boolean

Whether the target year is a leap year

hours *number | string

The remaining hours (adjusted for 12/24-hour format)

minutes *number | string

The remaining minutes

seconds *number | string

The remaining seconds

milliseconds *number

The remaining milliseconds

amPm *'AM' | 'PM' | undefined

Whether the time is AM or PM (only when use24Hours is false)

isCompleted *boolean

Whether the countdown has completed (reached zero)

isRunning *boolean

Whether the countdown is currently running

totalMilliseconds *number

Total remaining time in milliseconds

start *function

Function to start the countdown

pause *function

Function to pause the countdown

resume *function

Function to resume a paused countdown

reset *function

Function to reset the countdown to its initial state