Timer

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

days

hours

minutes

seconds

Anatomy

<Timer.Root>
  <Timer.Area>
    <Timer.Item />
    <Timer.Separator />
  </Timer.Area>
  <Timer.Control>
    <Timer.ActionTrigger />
  </Timer.Control>
</Timer.Root>

Examples

Countdown

You can create a countdown timer by setting the countdown prop to true and startMs to the initial time:

Interval

Use the interval prop to control how frequently the timer updates. This is useful for displaying milliseconds:

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.

Pomodoro

Here's an example of building a pomodoro timer that alternates between work and break sessions:

Root Provider

An alternative way to control the timer is to use the RootProvider component and the useTimer hook. This way you can access the state and methods from outside the component.

API Reference

Props

Root

Renders a <div> element.

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

Renders a <button> element.

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

Renders a <div> element.

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

Renders a <div> element.

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

Renders a <div> element.

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.

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

CSS Variable	Description
`--value`	The current value

RootProvider

Renders a <div> element.

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

Renders a <div> element.

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

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.