# Timer

URL: https://ark-ui.com/docs/components/timer
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/timer.mdx

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

---

<ComponentPreview id="Timer" />

## Examples

Learn how to use the `Timer` component in your project. Let's take a look at the most basic example:

**Example: basic**

#### React

```tsx
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>
)

```

#### Solid

```tsx
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>
)

```

#### Vue

```vue
<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>

```

#### Svelte

```svelte
<script lang="ts">
  import { Timer } from '@ark-ui/svelte/timer'
</script>

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

```

### Countdown Timer

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

**Example: countdown**

#### React

```tsx
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>
)

```

#### Solid

```tsx
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>
)

```

#### Vue

```vue
<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>

```

#### Svelte

```svelte
<script lang="ts">
  import { Timer } from '@ark-ui/svelte/timer'
</script>

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

```

### 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: events**

#### React

```tsx
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>
)

```

#### Solid

```tsx
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>
)

```

#### Vue

```vue
<script setup lang="ts">
import { Timer } from '@ark-ui/vue/timer'
</script>

<template>
  <Timer.Root
    :autoStart="true"
    :countdown="true"
    :startMs="5 * 1000"
    @complete="() => console.log('Timer completed')"
    @tick="(details) => console.log('Tick:', details.formattedTime)"
  >
    <Timer.Item type="seconds" />
  </Timer.Root>
</template>

```

#### Svelte

```svelte
<script lang="ts">
  import { Timer, type TimerTickDetails } from '@ark-ui/svelte/timer'

  const handleComplete = () => console.log('Timer completed')
  const handleTick = (details: TimerTickDetails) => console.log('Tick:', details.formattedTime)
</script>

<Timer.Root targetMs={5 * 1000} onComplete={handleComplete} onTick={handleTick}>
  <Timer.Item type="seconds" />
</Timer.Root>

```

### 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: root-provider**

#### React

```tsx
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>
    </>
  )
}

```

#### Solid

```tsx
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>
    </>
  )
}

```

#### Vue

```vue
<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>

```

#### Svelte

```svelte
<script lang="ts">
  import { Timer, useTimer } from '@ark-ui/svelte/timer'

  const id = $props.id()
  const timer = useTimer({ id, targetMs: 60 * 60 * 1000 })
</script>

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

```

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

## API Reference

### Props

**Component API Reference**

#### React

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoStart` | `boolean` | No | Whether the timer should start automatically |
| `countdown` | `boolean` | No | Whether the timer should countdown, decrementing the timer on each tick. |
| `ids` | `Partial<{ root: string; area: string }>` | No | The ids of the timer parts |
| `interval` | `number` | No | The interval in milliseconds to update the timer count. |
| `onComplete` | `() => void` | No | Function invoked when the timer is completed |
| `onTick` | `(details: TickDetails) => void` | No | Function invoked when the timer ticks |
| `startMs` | `number` | No | The total duration of the timer in milliseconds. |
| `targetMs` | `number` | No | The minimum count of the timer in milliseconds. |


**ActionTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `action` | `TimerAction` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Area Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `type` | `keyof Time<number>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Data Attributes:**

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


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseTimerReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Separator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Solid

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoStart` | `boolean` | No | Whether the timer should start automatically |
| `countdown` | `boolean` | No | Whether the timer should countdown, decrementing the timer on each tick. |
| `ids` | `Partial<{ root: string; area: string }>` | No | The ids of the timer parts |
| `interval` | `number` | No | The interval in milliseconds to update the timer count. |
| `onComplete` | `() => void` | No | Function invoked when the timer is completed |
| `onTick` | `(details: TickDetails) => void` | No | Function invoked when the timer ticks |
| `startMs` | `number` | No | The total duration of the timer in milliseconds. |
| `targetMs` | `number` | No | The minimum count of the timer in milliseconds. |


**ActionTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `action` | `TimerAction` | Yes |  |
| `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Area Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `type` | `keyof Time<number>` | Yes |  |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Data Attributes:**

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


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseTimerReturn` | Yes |  |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Separator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Vue

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoStart` | `boolean` | No | Whether the timer should start automatically |
| `countdown` | `boolean` | No | Whether the timer should countdown, decrementing the timer on each tick. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; area: string }>` | No | The ids of the timer parts |
| `interval` | `number` | No | The interval in milliseconds to update the timer count. |
| `startMs` | `number` | No | The total duration of the timer in milliseconds. |
| `targetMs` | `number` | No | The minimum count of the timer in milliseconds. |


**ActionTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `action` | `TimerAction` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Area Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `type` | `keyof Time<number>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Data Attributes:**

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


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `TimerApi<PropTypes>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Separator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Svelte

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoStart` | `boolean` | No | Whether the timer should start automatically |
| `countdown` | `boolean` | No | Whether the timer should countdown, decrementing the timer on each tick. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; area: string }>` | No | The ids of the timer parts |
| `interval` | `number` | No | The interval in milliseconds to update the timer count. |
| `onComplete` | `() => void` | No | Function invoked when the timer is completed |
| `onTick` | `(details: TickDetails) => void` | No | Function invoked when the timer ticks |
| `ref` | `Element` | No |  |
| `startMs` | `number` | No | The total duration of the timer in milliseconds. |
| `targetMs` | `number` | No | The minimum count of the timer in milliseconds. |


**ActionTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `action` | `TimerAction` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Area Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Context Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `api` | `Snippet<[UseTimerContext]>` | No |  |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `type` | `keyof Time<number>` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Item Data Attributes:**

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


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseTimerReturn` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Separator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


### Context

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

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `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. |