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:

Example not found

Example not found

Example not found

Example not found

Countdown Timer

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

Example not found

Example not found

Example not found

Example not found

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.

Example not found

Example not found

Example not found

Example not found

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.

Example not found

Example not found

Example not found

Example not found

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

API Reference

Props

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`	`1000`	`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.

CSS Variable	Description
`--value`	The current value

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.

Context

These are the properties available when using Timer.Context, useTimerContext hook or useTimer hook.

API

Property	Type
`running`	`boolean` Whether the timer is running.
`paused`	`boolean` Whether the timer is paused.
`time`	`Time<number>` The formatted timer count value.
`formattedTime`	`Time<string>` The formatted time parts of the timer count.
`start`	`VoidFunction` Function to start the timer.
`pause`	`VoidFunction` Function to pause the timer.
`resume`	`VoidFunction` Function to resume the timer.
`reset`	`VoidFunction` Function to reset the timer.
`restart`	`VoidFunction` Function to restart the timer.
`progressPercent`	`number` The progress percentage of the timer.