---
id: timer
title: Timer
description: Used to record the time elapsed from zero or since a specified target time.
---

<ComponentPreview id="Timer" />

## Anatomy

<Anatomy id="timer" />

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

## Examples

<Example id="basic" />

### Countdown

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

<Example id="countdown" />

### Interval

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

<Example id="interval" />

### 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 id="events" />

### Pomodoro

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

<Example id="pomodoro" />

### 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.

<Example id="root-provider" />

## API Reference

### Props

<ComponentTypes id="timer" />

### Context

<ContextType id="timer" />
