Timer

Controllable countdown and stopwatch timer

Usage

Timer is a stopwatch and countdown that can be started, paused, resumed, reset and restarted. It does not render playback buttons: add them with Timer.Control or control the timer with useTimer. Set autoStart to start the timer on mount:

00:01:30
import { Timer } from '@mantine/core';

function Demo() {
  return <Timer countdown startMs={90 * 1000} autoStart />;
}

Countdown and stopwatch

By default, Timer counts up from startMs. Set countdown prop to count down from startMs to targetMs instead. In both modes the timer stops at targetMs and calls onComplete:

import { Timer } from '@mantine/core';

function Demo() {
  return (
    <>
      {/* Stopwatch: counts up from 0 */}
      <Timer autoStart />

      {/* Countdown: counts down from 90 seconds to 0 */}
      <Timer countdown startMs={90 * 1000} autoStart />
    </>
  );
}

Changing startMs or countdown stops the timer and resets it to the new startMs.

Format

Set format prop to change the readout, 'HH:mm:ss' by default:

TokenDescriptionExample
DD / DDays, padded to 2 digits / not padded02 / 2
HH / HHours (0–23), padded / not padded09 / 9
mm / mMinutes (0–59), padded / not padded05 / 5
ss / sSeconds (0–59), padded / not padded07 / 7
SSSMilliseconds, padded to 3 digits040
SSCentiseconds, padded to 2 digits04
SMilliseconds, not padded40

Literal text is not escaped: token letters are replaced with time values even inside words. All tokens except days are capped to their natural range, include a larger token for durations that exceed the largest unit in the format:

11:25:15
05:30
02:06:00:00
import { Stack, Timer } from '@mantine/core';

function Demo() {
  return (
    <Stack align="center">
      <Timer countdown startMs={41_115_000} format="HH:mm:ss" autoStart />
      <Timer countdown startMs={330_000} format="mm:ss" autoStart />
      <Timer countdown startMs={194_400_000} format="DD:HH:mm:ss" autoStart />
    </Stack>
  );
}

To display milliseconds, lower the interval prop so the readout updates more often than once per second:

00:00:00
import { Timer } from '@mantine/core';

function Demo() {
  return <Timer format="mm:ss:SS" interval={10} autoStart />;
}

Custom layout

Pass Timer.Segment, Timer.Separator and Timer.Control as children to replace the default readout. Timer.Control is a button that calls the controller action set with the action prop:

0500
import { ActionIcon, Group, Timer } from '@mantine/core';
import { ArrowCounterClockwiseIcon, PauseIcon, PlayIcon } from '@phosphor-icons/react';

function Demo() {
  return (
    <Timer countdown startMs={5 * 60 * 1000} autoStart>
      <Group gap={4} fz={36} fw={700}>
        <Timer.Segment type="minutes" />
        <Timer.Separator>:</Timer.Separator>
        <Timer.Segment type="seconds" />
      </Group>

      <Group gap="xs">
        <Timer.Control action="start" aria-label="Start">
          <ActionIcon component="span" variant="light">
            <PlayIcon size={18} weight="fill" />
          </ActionIcon>
        </Timer.Control>
        <Timer.Control action="pause" aria-label="Pause">
          <ActionIcon component="span" variant="light">
            <PauseIcon size={18} weight="fill" />
          </ActionIcon>
        </Timer.Control>
        <Timer.Control action="restart" aria-label="Restart">
          <ActionIcon component="span" variant="light">
            <ArrowCounterClockwiseIcon size={18} />
          </ActionIcon>
        </Timer.Control>
      </Group>
    </Timer>
  );
}

useTimer hook

Timer supports the controller pattern with the useTimer hook. It accepts the same options as Timer props and returns the timer state and actions:

import { useTimer } from '@mantine/core';

function Demo() {
  const controller = useTimer({ countdown: true, startMs: 60 * 1000 });

  controller.getValue(); // -> { totalMs, days, hours, minutes, seconds, milliseconds }
  controller.isRunning(); // -> boolean, true while the timer is counting
  controller.isPaused(); // -> boolean, true when the timer is started and then paused
  controller.getProgress(); // -> number from 0 to 1 when the boundary is set

  controller.start(); // starts from the current value, or from startMs after the timer has completed
  controller.pause();
  controller.resume();
  controller.reset(); // stops and resets the value to startMs
  controller.restart(); // resets and starts again

  return null;
}

Controlling the timer

Pass the controller created with useTimer to the controller prop. Timer options set on Timer are then ignored, pass them to useTimer instead:

01:00:00

running: false, paused: false

import { Button, Group, Stack, Text, Timer, useTimer } from '@mantine/core';

function Demo() {
  const controller = useTimer({ countdown: true, startMs: 60 * 1000, interval: 100 });

  return (
    <Stack align="center">
      <Timer controller={controller} format="mm:ss:SS" fz={40} fw={700} />

      <Text c="dimmed" size="sm">
        running: {String(controller.isRunning())}, paused: {String(controller.isPaused())}
      </Text>

      <Group>
        <Button onClick={controller.start} disabled={controller.isRunning()}>Start</Button>
        <Button onClick={controller.pause} disabled={!controller.isRunning()} variant="default">Pause</Button>
        <Button onClick={controller.resume} disabled={controller.isRunning()} variant="default">Resume</Button>
        <Button onClick={controller.reset} variant="default">Reset</Button>
        <Button onClick={controller.restart} variant="default">Restart</Button>
      </Group>
    </Stack>
  );
}

Progress

When targetMs is set, getProgress() returns a value from 0 to 1. Use it with Progress or RingProgress:

30:000
import { Progress, Stack, Timer, useTimer } from '@mantine/core';

function Demo() {
  const controller = useTimer({ countdown: true, startMs: 30 * 1000, autoStart: true, interval: 50 });

  return (
    <Stack>
      <Timer controller={controller} format="ss:SSS" fz={32} fw={700} style={{ alignSelf: 'center' }} />
      <Progress value={controller.getProgress() * 100} transitionDuration={50} />
    </Stack>
  );
}

Timer.parse

Timer.parse (also available as useTimer.parse) converts a duration object, Date or ISO date string to milliseconds:

import { Timer } from '@mantine/core';

Timer.parse(90 * 1000); // -> 90000
Timer.parse({ minutes: 25 }); // -> 1500000
Timer.parse({ hours: 1, minutes: 30 }); // -> 5400000
Timer.parse('2030-01-01T00:00:00'); // -> milliseconds from now until the date

With a Date or a date string, the result depends on the current time. Calculate it once, for example, in a useState initializer: a new startMs value on every render resets the timer:

1135:07:52:59
import { useState } from 'react';
import { Timer } from '@mantine/core';

function Demo() {
  const [remaining] = useState(() => Timer.parse('2030-01-01T00:00:00'));
  return <Timer countdown startMs={remaining} format="DD:HH:mm:ss" autoStart />;
}

Timer vs use-countdown

use-countdown is a display-only countdown hook. Use Timer or useTimer when the timer must count up or be paused, resumed and restarted.

Accessibility

Set aria-label on icon-only timer controls. If ticks need to be announced, use aria-live="polite" with an interval of at least one second:

import { Timer } from '@mantine/core';

function Demo() {
  return (
    <Timer countdown startMs={60 * 1000} interval={1000} aria-live="polite">
      <Timer.Segment type="minutes" />
      <Timer.Separator />
      <Timer.Segment type="seconds" />
      <Timer.Control action="start" aria-label="Start timer">
        ▶
      </Timer.Control>
    </Timer>
  );
}