# or
yarn add @zag-js/timer @zag-js/react
```

## Anatomy

To set up the Timer correctly, you'll need to understand its anatomy and how we
name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

First, import the timer package into your project

```jsx
import * as timer from "@zag-js/timer"
```

The Timer package exports these functions:

- `machine` â The state machine logic for the Time Picker widget.
- `connect` â The function that translates the machine's state to JSX attributes
  and event handlers.
- `parse` â The function to parse a date time string or object into a `Time`
  object.

> You'll also need to provide a unique `id` to the `useMachine` hook. This is
> used to ensure that every part has a unique identifier.

Next, import the required hooks and functions for your framework and use the
Time Picker machine in your project ð¥

```jsx
import { normalizeProps, useMachine } from "@zag-js/react"
import * as timer from "@zag-js/timer"

export function Countdown() {
  const service = useMachine(timer.machine, {
    id: useId(),
    countdown: true,
    autoStart: true,
    startMs: timer.parse({ days: 2, seconds: 10 }),
  })

  const api = timer.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getAreaProps()}>
        <div {...api.getItemProps({ type: "days" })}>
          {api.formattedTime.days}
        </div>
        <div {...api.getSeparatorProps()}>:</div>
        <div {...api.getItemProps({ type: "hours" })}>
          {api.formattedTime.hours}
        </div>
        <div {...api.getSeparatorProps()}>:</div>
        <div {...api.getItemProps({ type: "minutes" })}>
          {api.formattedTime.minutes}
        </div>
        <div {...api.getSeparatorProps()}>:</div>
        <div {...api.getItemProps({ type: "seconds" })}>
          {api.formattedTime.seconds}
        </div>
      </div>
      <div {...api.getControlProps()}>
        <button {...api.getActionTriggerProps({ action: "start" })}>
          START
        </button>
        <button {...api.getActionTriggerProps({ action: "pause" })}>
          PAUSE
        </button>
        <button {...api.getActionTriggerProps({ action: "resume" })}>
          RESUME
        </button>
        <button {...api.getActionTriggerProps({ action: "reset" })}>
          RESET
        </button>
      </div>
    </div>
  )
}
```

### Setting the start value

Set the `startMs` property to the timer machine's context to set the start time
in milliseconds.

```jsx
const service = useMachine(timer.machine, {
  startMs: 1000 * 60 * 60, // 1 hour
})
```

Alternatively, you can also use the `timer.parse` function to convert a date
time string or object into milliseconds

```jsx
const service = useMachine(timer.machine, {
  startMs: timer.parse("2021-01-01T12:00:00Z"),
  // startMs: timer.parse({ hours: 12, minutes: 0, seconds: 0 }),
})
```

### Auto starting the timer

Set the `autoStart` property to `true` in the timer machine's context to start
the timer automatically when the component mounts.

```jsx
const service = useMachine(timer.machine, {
  autoStart: true,
})
```

### Usage as countdown timer

To use the timer as a countdown timer, set the `countdown` property to `true` in
the timer machine's context.

```jsx
const service = useMachine(timer.machine, {
  countdown: true,
})
```

### Setting the target value

To set the target value of the countdown timer, pass the `targetMs` property in
the timer machine's context. The timer stops automatically when the `targetMs`
is reached.

When `targetMs` is set and `countdown=true`, the timer ticks down to zero from
the specified target time.

```jsx
const service = useMachine(timer.machine, {
  countdown: true,
  targetMs: 1000 * 60 * 60, // 1 hour
})
```

When `targetMs` is set and `countdown=false|undefined`, the timer ticks up to
the specified target time.

```jsx
const service = useMachine(timer.machine, {
  targetMs: 1000 * 60 * 60, // 1 hour
})
```

### Setting the tick interval

Set the `interval` property to the timer machine's context to set the tick
interval in milliseconds.

```jsx
const service = useMachine(timer.machine, {
  interval: 1000, // 1 second
})
```

### Listening to tick events

When the timer ticks, the `onTick` callback is invoke. You can listen to this
event and update your UI accordingly.

```jsx
const service = useMachine(timer.machine, {
  onTick(details) {
    // details => { value, segments }
    console.log(details)
  },
})
```

### Listening for completion events

When the timer reaches the target time, the `onComplete` callback is invoked.

```jsx
const service = useMachine(timer.machine, {
  countdown: true,
  targetMs: 1000 * 60 * 60, // 1 hour
  onComplete() {
    console.log("Timer completed")
  },
})
```

### Starting and Stopping the timer

To start the timer, send the `api.start()` callback

```jsx
api.start()
```

To stop the timer, send the `api.stop()` callback

```jsx
api.stop()
```

### Pausing and Resuming the timer

To pause the timer, send the `api.pause()` callback

```jsx
api.pause()
```

To resume the timer, send the `api.resume()` callback

```jsx
api.resume()
```

## Methods and Properties

### Machine Context

The time picker machine exposes the following context properties:

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

**`countdown`**
Type: `boolean`
Description: Whether the timer should countdown, decrementing the timer on each tick.

**`startMs`**
Type: `number`
Description: The total duration of the timer in milliseconds.

**`targetMs`**
Type: `number`
Description: The minimum count of the timer in milliseconds.

**`autoStart`**
Type: `boolean`
Description: Whether the timer should start automatically

**`interval`**
Type: `number`
Description: The interval in milliseconds to update the timer count.

**`onTick`**
Type: `(details: TickDetails) => void`
Description: Function invoked when the timer ticks

**`onComplete`**
Type: `() => void`
Description: Function invoked when the timer is completed

**`id`**
Type: `string`
Description: The unique identifier of the machine.

**`getRootNode`**
Type: `() => ShadowRoot | Node | Document`
Description: A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

### Machine API

The time picker `api` exposes the following methods:

**`running`**
Type: `boolean`
Description: Whether the timer is running.

**`paused`**
Type: `boolean`
Description: Whether the timer is paused.

**`time`**
Type: `Time<number>`
Description: The formatted timer count value.

**`formattedTime`**
Type: `Time<string>`
Description: The formatted time parts of the timer count.

**`start`**
Type: `VoidFunction`
Description: Function to start the timer.

**`pause`**
Type: `VoidFunction`
Description: Function to pause the timer.

**`resume`**
Type: `VoidFunction`
Description: Function to resume the timer.

**`reset`**
Type: `VoidFunction`
Description: Function to reset the timer.

**`restart`**
Type: `VoidFunction`
Description: Function to restart the timer.

**`progressPercent`**
Type: `number`
Description: The progress percentage of the timer.
The toast component is used to give feedback to users after an action has taken
place.

## Resources


[Latest version: v1.33.1](https://www.npmjs.com/package/@zag-js/toast)
[Logic Visualizer](https://zag-visualizer.vercel.app/toast)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/toast)



**Features**

- Support for screen readers
- Limit the number of visible toasts
- Manage promises within toast
- Pause on hover, focus or page idle
- Can remove or update toast programmatically

## Installation

To use the toast machine in your project, run the following command in your
command line:

```bash
npm install @zag-js/toast @zag-js/react