Timer

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

days

hours

minutes

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

import { Timer } from '@ark-ui/solid/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>
)

<script setup lang="ts">
import { Timer } from '@ark-ui/vue/timer'
</script>

<template>
  <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>
</template>

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

import { Timer } from '@ark-ui/solid/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>
)

<script setup lang="ts">
import { Timer } from '@ark-ui/vue/timer'
</script>

<template>
  <Timer.Root :autoStart="true" :countdown="true" :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>
</template>

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

import { Timer } from '@ark-ui/solid/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>
)

<script setup lang="ts">
import { Timer } from '@ark-ui/vue/timer'
</script>

<template>
  <Timer.Root
    :targetMs="5 * 1000"
    @complete="() => console.log('Timer completed')"
    @tick="(details) => console.log('Tick:', details.formattedTime)"
  >
    <Timer.Item type="seconds" />
  </Timer.Root>
</template>

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

import { Timer, useTimer } from '@ark-ui/solid/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>
    </>
  )
}

<script setup lang="ts">
import { Timer, useTimer } from '@ark-ui/vue/timer'

const timer = useTimer({ targetMs: 60 * 60 * 1000 })
</script>

<template>
  <button @click="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>
</template>

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

API Reference

Root

Prop	Default	Type
`asChild`		`(props: ParentProps<'div'>) => Element` 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
`interval`	`250`	`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

Prop	Default	Type
`action`		`TimerAction`
`asChild`		`(props: ParentProps<'button'>) => Element` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Area

Prop	Default	Type
`asChild`		`(props: ParentProps<'div'>) => Element` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Control

Prop	Default	Type
`asChild`		`(props: ParentProps<'div'>) => Element` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Item

Prop	Default	Type
`type`		`keyof Time<number>`
`asChild`		`(props: ParentProps<'div'>) => Element` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Data Attribute	Value
`[data-scope]`	timer
`[data-part]`	item
`[data-type]`	The type of the item

RootProvider

Prop	Default	Type
`value`		`UseTimerReturn`
`asChild`		`(props: ParentProps<'div'>) => Element` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Separator

Prop	Default	Type
`asChild`		`(props: ParentProps<'div'>) => Element` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.