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 theRoot
component.
API Reference
Root
Prop | Default | Type |
---|---|---|
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 | |
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 | boolean 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 | boolean 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 | boolean 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 | boolean 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 | boolean 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 | boolean Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |