Components
Timer

Timer

Used to record the time elapsed from zero or since a specified target time.

01

days

16

hours

00

minutes

00

seconds

Examples

Learn how to use the Timer component in your project. Let's take a look at the most basic example:

import { Timer } from '@ark-ui/react/timer'

export const Basic = () => (
  <Timer.Root targetMs={60 * 60 * 1000}>
    <Timer.Area>
      <Timer.Item type="days" />
      <Timer.Separator>:</Timer.Separator>
      <Timer.Item type="hours" />
      <Timer.Separator>:</Timer.Separator>
      <Timer.Item type="minutes" />
      <Timer.Separator>:</Timer.Separator>
      <Timer.Item type="seconds" />
    </Timer.Area>
    <Timer.Control>
      <Timer.ActionTrigger action="start">Play</Timer.ActionTrigger>
      <Timer.ActionTrigger action="resume">Resume</Timer.ActionTrigger>
      <Timer.ActionTrigger action="pause">Pause</Timer.ActionTrigger>
    </Timer.Control>
  </Timer.Root>
)

Countdown Timer

You can create a countdown timer by setting the targetMs prop to a future timestamp:

import { Timer } from '@ark-ui/react/timer'

export const Countdown = () => (
  <Timer.Root autoStart countdown startMs={60 * 60 * 500}>
    <Timer.Area>
      <Timer.Item type="days" />
      <Timer.Separator>:</Timer.Separator>
      <Timer.Item type="hours" />
      <Timer.Separator>:</Timer.Separator>
      <Timer.Item type="minutes" />
      <Timer.Separator>:</Timer.Separator>
      <Timer.Item type="seconds" />
    </Timer.Area>
  </Timer.Root>
)

Timer Events

The Timer component provides events that you can listen to for various timer-related actions.

  • The onComplete event is triggered when the timer reaches its target time.
  • The onTick event is called on each timer update, providing details about the current timer state.
import { Timer } from '@ark-ui/react/timer'

export const Events = () => (
  <Timer.Root
    targetMs={5 * 1000}
    onComplete={() => console.log('Timer completed')}
    onTick={(details) => console.log('Tick:', details.formattedTime)}
  >
    <Timer.Item type="seconds" />
  </Timer.Root>
)

Using the Root Provider

The RootProvider component provides a context for the timer. It accepts the value of the useTimer hook. You can leverage it to access the component state and methods from outside the timer.

import { Timer, useTimer } from '@ark-ui/react/timer'

export const RootProvider = () => {
  const timer = useTimer({ targetMs: 60 * 60 * 1000 })

  return (
    <>
      <button onClick={() => timer.pause()}>Pause</button>

      <Timer.RootProvider value={timer}>
        <Timer.Area>
          <Timer.Item type="days" />
          <Timer.Separator>:</Timer.Separator>
          <Timer.Item type="hours" />
          <Timer.Separator>:</Timer.Separator>
          <Timer.Item type="minutes" />
          <Timer.Separator>:</Timer.Separator>
          <Timer.Item type="seconds" />
        </Timer.Area>
        <Timer.Control>
          <Timer.ActionTrigger action="start">Play</Timer.ActionTrigger>
          <Timer.ActionTrigger action="resume">Resume</Timer.ActionTrigger>
          <Timer.ActionTrigger action="pause">Pause</Timer.ActionTrigger>
        </Timer.Control>
      </Timer.RootProvider>
    </>
  )
}

If you're using the RootProvider component, you don't need to use the Root component.

API Reference

Root

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
autoStart
boolean

Whether the timer should start automatically

countdown
boolean

Whether the timer should countdown, decrementing the timer on each tick.

ids
Partial<{ root: string; area: string }>

The ids of the timer parts

interval250
number

The interval in milliseconds to update the timer count.

onComplete
() => void

Function invoked when the timer is completed

onTick
(details: TickDetails) => void

Function invoked when the timer ticks

startMs
number

The total duration of the timer in milliseconds.

targetMs
number

The minimum count of the timer in milliseconds.

ActionTrigger

PropDefaultType
action
TimerAction

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Area

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Control

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Item

PropDefaultType
type
keyof Time<number>

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]timer
[data-part]item
[data-type]The type of the item

RootProvider

PropDefaultType
value
UseTimerReturn

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Separator

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.