# Timer

URL: https://ark-ui.com/docs/components/timer
LLM: https://ark-ui.com/llms.txt/components/timer

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

---



## Anatomy



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

## Examples

```tsx
import { Timer } from '@ark-ui/react/timer'
import { PauseIcon, PlayIcon } from 'lucide-react'
import button from 'styles/button.module.css'
import styles from 'styles/timer.module.css'

export const Basic = () => (
  <Timer.Root className="stack" targetMs={60 * 60 * 1000} startMs={40 * 60 * 1000}>
    <Timer.Area className={styles.Area}>
      <div className={styles.ItemGroup}>
        <Timer.Item className={styles.Item} type="days" />
        <span className={styles.ItemLabel}>days</span>
      </div>
      <Timer.Separator className={styles.Separator}>:</Timer.Separator>
      <div className={styles.ItemGroup}>
        <Timer.Item className={styles.Item} type="hours" />
        <span className={styles.ItemLabel}>hours</span>
      </div>
      <Timer.Separator className={styles.Separator}>:</Timer.Separator>
      <div className={styles.ItemGroup}>
        <Timer.Item className={styles.Item} type="minutes" />
        <span className={styles.ItemLabel}>minutes</span>
      </div>
      <Timer.Separator className={styles.Separator}>:</Timer.Separator>
      <div className={styles.ItemGroup}>
        <Timer.Item className={styles.Item} type="seconds" />
        <span className={styles.ItemLabel}>seconds</span>
      </div>
    </Timer.Area>
    <Timer.Control className="hstack">
      <Timer.ActionTrigger className={button.Root} action="start">
        <PlayIcon /> Play
      </Timer.ActionTrigger>
      <Timer.ActionTrigger className={button.Root} action="resume">
        <PlayIcon /> Resume
      </Timer.ActionTrigger>
      <Timer.ActionTrigger className={button.Root} action="pause">
        <PauseIcon /> Pause
      </Timer.ActionTrigger>
    </Timer.Control>
  </Timer.Root>
)
```

### Countdown

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

```tsx
import { Timer } from '@ark-ui/react/timer'
import { PauseIcon, PlayIcon, RotateCcwIcon } from 'lucide-react'
import button from 'styles/button.module.css'
import styles from 'styles/timer.module.css'

export const Countdown = () => (
  <Timer.Root className="stack" countdown startMs={5 * 60 * 1000}>
    <Timer.Area className={styles.Area}>
      <div className={styles.ItemGroup}>
        <Timer.Item className={styles.Item} type="minutes" />
        <span className={styles.ItemLabel}>minutes</span>
      </div>
      <Timer.Separator className={styles.Separator}>:</Timer.Separator>
      <div className={styles.ItemGroup}>
        <Timer.Item className={styles.Item} type="seconds" />
        <span className={styles.ItemLabel}>seconds</span>
      </div>
    </Timer.Area>
    <Timer.Control className="hstack">
      <Timer.ActionTrigger className={button.Root} action="start">
        <PlayIcon /> Start
      </Timer.ActionTrigger>
      <Timer.ActionTrigger className={button.Root} action="pause">
        <PauseIcon /> Pause
      </Timer.ActionTrigger>
      <Timer.ActionTrigger className={button.Root} action="reset">
        <RotateCcwIcon /> Reset
      </Timer.ActionTrigger>
    </Timer.Control>
  </Timer.Root>
)
```

### Interval

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

```tsx
import { Timer } from '@ark-ui/react/timer'
import { PauseIcon, PlayIcon, RotateCcwIcon } from 'lucide-react'
import button from 'styles/button.module.css'
import styles from 'styles/timer.module.css'

export const Interval = () => (
  <Timer.Root className="stack" interval={100} targetMs={60 * 1000}>
    <Timer.Area className={styles.Area}>
      <div className={styles.ItemGroup}>
        <Timer.Item className={styles.Item} type="seconds" />
        <span className={styles.ItemLabel}>seconds</span>
      </div>
      <Timer.Separator className={styles.Separator}>.</Timer.Separator>
      <div className={styles.ItemGroup}>
        <Timer.Item className={styles.Item} type="milliseconds" />
        <span className={styles.ItemLabel}>ms</span>
      </div>
    </Timer.Area>
    <Timer.Control className="hstack">
      <Timer.ActionTrigger className={button.Root} action="start">
        <PlayIcon /> Start
      </Timer.ActionTrigger>
      <Timer.ActionTrigger className={button.Root} action="pause">
        <PauseIcon /> Pause
      </Timer.ActionTrigger>
      <Timer.ActionTrigger className={button.Root} action="reset">
        <RotateCcwIcon /> Reset
      </Timer.ActionTrigger>
    </Timer.Control>
  </Timer.Root>
)
```

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

```tsx
import { Timer } from '@ark-ui/react/timer'
import { PlayIcon, RotateCcwIcon } from 'lucide-react'
import { useState } from 'react'
import button from 'styles/button.module.css'
import styles from 'styles/timer.module.css'

export const Events = () => {
  const [ticks, setTicks] = useState(0)

  return (
    <Timer.Root
      className="stack"
      targetMs={60 * 1000}
      onComplete={() => console.log('Timer completed')}
      onTick={() => setTicks((t) => t + 1)}
    >
      <Timer.Area className={styles.Area}>
        <div className={styles.ItemGroup}>
          <Timer.Item className={styles.Item} type="minutes" />
          <span className={styles.ItemLabel}>minutes</span>
        </div>
        <Timer.Separator className={styles.Separator}>:</Timer.Separator>
        <div className={styles.ItemGroup}>
          <Timer.Item className={styles.Item} type="seconds" />
          <span className={styles.ItemLabel}>seconds</span>
        </div>
      </Timer.Area>

      <Timer.Control className="hstack">
        <Timer.ActionTrigger className={button.Root} action="start">
          <PlayIcon /> Start
        </Timer.ActionTrigger>
        <Timer.ActionTrigger className={button.Root} action="reset">
          <RotateCcwIcon /> Reset
        </Timer.ActionTrigger>
      </Timer.Control>

      <output>Ticks: {ticks}</output>
    </Timer.Root>
  )
}
```

### Pomodoro

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

```tsx
import { Timer } from '@ark-ui/react/timer'
import { PauseIcon, PlayIcon, RotateCcwIcon } from 'lucide-react'
import { useState } from 'react'
import button from 'styles/button.module.css'
import styles from 'styles/timer.module.css'

export const Pomodoro = () => {
  const [isWorking, setIsWorking] = useState(true)
  const [cycles, setCycles] = useState(0)

  const handleComplete = () => {
    setIsWorking(!isWorking)
    if (!isWorking) setCycles((c) => c + 1)
  }

  return (
    <Timer.Root
      className="stack"
      startMs={isWorking ? 25 * 60 * 1000 : 5 * 60 * 1000}
      countdown
      onComplete={handleComplete}
    >
      <h2>{isWorking ? 'Work Session' : 'Break Session'}</h2>

      <Timer.Area className={styles.Area}>
        <div className={styles.ItemGroup}>
          <Timer.Item className={styles.Item} type="minutes" />
          <span className={styles.ItemLabel}>minutes</span>
        </div>
        <Timer.Separator className={styles.Separator}>:</Timer.Separator>
        <div className={styles.ItemGroup}>
          <Timer.Item className={styles.Item} type="seconds" />
          <span className={styles.ItemLabel}>seconds</span>
        </div>
      </Timer.Area>

      <Timer.Control className="hstack">
        <Timer.ActionTrigger className={button.Root} action="start">
          <PlayIcon /> Start
        </Timer.ActionTrigger>
        <Timer.ActionTrigger className={button.Root} action="pause">
          <PauseIcon /> Pause
        </Timer.ActionTrigger>
        <Timer.ActionTrigger className={button.Root} action="reset">
          <RotateCcwIcon /> Reset
        </Timer.ActionTrigger>
      </Timer.Control>

      <output>Completed cycles: {cycles}</output>
    </Timer.Root>
  )
}
```

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

```tsx
import { Timer, useTimer } from '@ark-ui/react/timer'
import { PauseIcon, PlayIcon, RotateCcwIcon } from 'lucide-react'
import button from 'styles/button.module.css'
import styles from 'styles/timer.module.css'

export const RootProvider = () => {
  const timer = useTimer({ targetMs: 60 * 60 * 1000 })

  return (
    <div className="stack">
      <output>timer: {JSON.stringify(timer.time)}</output>
      <Timer.RootProvider className={styles.Root} value={timer}>
        <Timer.Area className={styles.Area}>
          <div className={styles.ItemGroup}>
            <Timer.Item className={styles.Item} type="hours" />
            <span className={styles.ItemLabel}>hours</span>
          </div>
          <Timer.Separator className={styles.Separator}>:</Timer.Separator>
          <div className={styles.ItemGroup}>
            <Timer.Item className={styles.Item} type="minutes" />
            <span className={styles.ItemLabel}>minutes</span>
          </div>
          <Timer.Separator className={styles.Separator}>:</Timer.Separator>
          <div className={styles.ItemGroup}>
            <Timer.Item className={styles.Item} type="seconds" />
            <span className={styles.ItemLabel}>seconds</span>
          </div>
        </Timer.Area>
        <Timer.Control className="hstack">
          <Timer.ActionTrigger className={button.Root} action="start">
            <PlayIcon /> Start
          </Timer.ActionTrigger>
          <Timer.ActionTrigger className={button.Root} action="resume">
            <PlayIcon /> Resume
          </Timer.ActionTrigger>
          <Timer.ActionTrigger className={button.Root} action="pause">
            <PauseIcon /> Pause
          </Timer.ActionTrigger>
          <Timer.ActionTrigger className={button.Root} action="reset">
            <RotateCcwIcon /> Reset
          </Timer.ActionTrigger>
        </Timer.Control>
      </Timer.RootProvider>
    </div>
  )
}
```

## API Reference

### Props

### Root

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`autoStart`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether the timer should start automatically

**`countdown`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether the timer should countdown, decrementing the timer on each tick.

**`ids`**
Type: `Partial<{ root: string; area: string }>`
Required: false
Default Value: `undefined`
Description: The ids of the timer parts

**`interval`**
Type: `number`
Required: false
Default Value: `1000`
Description: The interval in milliseconds to update the timer count.

**`onComplete`**
Type: `() => void`
Required: false
Default Value: `undefined`
Description: Function invoked when the timer is completed

**`onTick`**
Type: `(details: TickDetails) => void`
Required: false
Default Value: `undefined`
Description: Function invoked when the timer ticks

**`startMs`**
Type: `number`
Required: false
Default Value: `undefined`
Description: The total duration of the timer in milliseconds.

**`targetMs`**
Type: `number`
Required: false
Default Value: `undefined`
Description: The minimum count of the timer in milliseconds.

**`translations`**
Type: `IntlTranslations`
Required: false
Default Value: `undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

### ActionTrigger

#### Props

**`action`**
Type: `TimerAction`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Area

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Control

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Item

#### Props

**`type`**
Type: `keyof Time<number>`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: timer
**`data-part`**: item
**`data-type`**: The type of the item

### RootProvider

#### Props

**`value`**
Type: `UseTimerReturn`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Separator

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `running` | `boolean` | Whether the timer is running. |
| `paused` | `boolean` | Whether the timer is paused. |
| `time` | `Time` | 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. |