@gfazioli/mantine-clock

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

Version

v1.0.3

Changelog

View the Changelog

Source

View source code

Package

@gfazioli/mantine-clock

Mantine Extensions

Docs

Edit this page

Built by

Giovambattista Fazioli (@gfazioli)

License

MIT

Support

Become a sponsor

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.

Running

Second hand behavior

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="" />
  );
}

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.

Default Static
(Current Time)

Static Time
15:30

With Seconds
09:45:30

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>
  );
}

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.

Starts at 08:00
(smooth animation)

Starts at 14:30:45
(tick animation)

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.

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.

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.

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

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.

Timezone

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:

New York

London

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.

Timezone

24 Hour Format

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:

Name	Type	Description
enabled	boolean	Whether the clock is active and updating
timezone	string	The timezone to use for the clock
updateFrequency	number	The frequency (in milliseconds) at which the clock updates
use24Hours	boolean	Whether to use 24-hour format or 12-hour format
padSeconds	boolean	Whether to pad single-digit seconds with a leading zero
padMinutes	boolean	Whether to pad single-digit minutes with a leading zero
padHours	boolean	Whether to pad single-digit hours with a leading zero

The hook returns an object with the following properties:

Name	Type	Description
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

Use case with Clock component

While useClock reports the current time, you can still build a "start from a specific time" experience by treating the hook as a ticker and managing the displayed time in local state.

This demo lets you pick hours, minutes, and seconds, then control the flow with Start, Pause, Resume and Reset. The Clock component receives the formatted HH:MM:SS value from state, while useClock provides a 1-second heartbeat and control methods.

Key ideas:

useClock({ enabled: false, updateFrequency: 1000 }) acts as a metronome when running.
Inputs set the displayed time while paused; during run, state advances every tick.
Reset returns the display to the selected inputs.

Set a specific time, then Start/Pause/Resume

Specific Time

Hours

Minutes

Seconds

10:15:00

Status: Paused

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

function Demo() {
  // Inputs to set a specific starting time
  const [hours, setHours] = useState(10);
  const [minutes, setMinutes] = useState(15);
  const [seconds, setSeconds] = useState(0);

  // Displayed time (driven by a metronome from useClock)
  const [display, setDisplay] = useState({ h: hours, m: minutes, s: seconds });

  // Use useClock purely as a ticker/controls (does not dictate displayed time)
  const clock = useClock({
    enabled: false, // start paused
    updateFrequency: 1000,
    padHours: true,
    padMinutes: true,
    padSeconds: true,
  });

  // When inputs change and we're paused, reflect them immediately on the display
  useEffect(() => {
    if (!clock.isRunning) {
      setDisplay({ h: hours, m: minutes, s: seconds });
    }
  }, [hours, minutes, seconds, clock.isRunning]);

  // Advance the displayed time by one second on each tick while running
  useEffect(() => {
    if (!clock.isRunning) return;
    setDisplay((prev) => {
      let s = prev.s + 1;
      let m = prev.m;
      let h = prev.h;
      if (s >= 60) {
        s = 0;
        m += 1;
        if (m >= 60) {
          m = 0;
          h = (h + 1) % 24;
        }
      }
      return { h, m, s };
    });
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [clock.seconds]);

  const pad = (n: number) => n.toString().padStart(2, '0');
  const value = pad(display.h) + ':' + pad(display.m) + ':' + pad(display.s);

  return (
    <Paper p="md" withBorder>
      <Group align="flex-start" gap="xl">
        {/* Analog clock showing the set/running time */}
        <Stack align="center" gap="md">
          <Clock value={value} running={false} size={300} />
          <Text size="sm" c="dimmed" ta="center">
            Set a specific time, then Start/Pause/Resume
          </Text>
        </Stack>

        {/* Controls */}
        <Stack gap="md" flex={1}>
          <Title order={4}>Specific Time</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">
            {pad(display.h)}:{pad(display.m)}:{pad(display.s)}
          </Text>

          <Text size="sm" c="dimmed" ta="center">
            Status: {clock.isRunning ? 'Running' : 'Paused'}
          </Text>

          <Group justify="center" gap="sm">
            <Button onClick={clock.start} disabled={clock.isRunning} variant="filled">
              Start
            </Button>
            <Button onClick={clock.pause} disabled={!clock.isRunning} variant="outline">
              Pause
            </Button>
            <Button onClick={clock.resume} disabled={clock.isRunning} variant="outline">
              Resume
            </Button>
            <Button
              onClick={() => {
                clock.reset();
                setDisplay({ h: hours, m: minutes, s: seconds });
              }}
              variant="light"
            >
              Reset
            </Button>
          </Group>
        </Stack>
      </Group>
    </Paper>
  );
}

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.

Hours

Minutes

Seconds

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:

Name	Type	Description
enabled	boolean	Whether the countdown is active and updating
timezone	string	The timezone to use for countdown calculations
updateFrequency	number	The frequency (in milliseconds) at which the countdown updates
use24Hours	boolean	Whether to use 24-hour format or 12-hour format
padSeconds	boolean	Whether to pad single-digit seconds with a leading zero
padMinutes	boolean	Whether to pad single-digit minutes with a leading zero
padHours	boolean	Whether to pad single-digit hours with a leading zero
targetDate	Date \| string	Target date for the countdown (Date object or ISO string)
hours	number	Number of hours to count down from current time
minutes	number	Number of minutes to count down from current time
seconds	number	Number of seconds to count down from current time
onCountDownCompleted	function	Callback function called when countdown reaches zero

The hook returns an object with the following properties:

Name	Type	Description
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

Use case with Clock component

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.

Reverse Clock
Counting Down

Countdown Settings

Hours

Minutes

Seconds

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>
  );
}

Mantine Clock

@gfazioli/mantine-clock

Installation

Usage

Static Clock with Value

Running Clock with Initial Value

Clock Hands

Clock Numbers

Clock Number Fonts

Styling with ClassNames

Available ClassNames

Neon Theme Example

Neon Cyber Clock Theme

Timezone Support

World Clocks Example

Supported Timezones

Usage Examples

Hooks

useClock Hook

Digital Clock with Controls

World Clocks with useClock

New York

London

Tokyo

Sydney

useClock API

Use case with Clock component

Specific Time

useClockCountDown Hook

Interactive Countdown Timer

Countdown to Specific Dates

🎊 New Year 2026

🎃 Halloween 2025

useClockCountDown API

Use case with Clock component

Countdown Settings

HIGHLIGHTS

RESOURCES

ECOSYSTEM