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

### Countdown Timer

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

<Example id="countdown" />

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

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

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