---
url: /reference/items/Timer/js-api.md
---
# JS API
## `Timer`
The base countdown component.
### Options
#### `delay`
* Type: `number`
* Default: `0`
The countdown duration, **in seconds**. `timer-end` is emitted once this delay has elapsed.
```html {3}
…
```
#### `repeat`
* Type: `boolean`
* Default: `false`
When enabled, the timer re-arms itself after each completion (interval mode), emitting `timer-tick` on every cycle in addition to `timer-end`.
```html {3}
…
```
#### `autostart`
* Type: `boolean`
* Default: `true`
Whether the countdown starts automatically on mount. Since the default is `true`, use the negated `data-option-no-autostart` attribute to require an explicit `start()`.
```html {3}
…
```
### Events
All events are dispatched as bubbling `CustomEvent`s on the component's element, so they can be listened to with [`Action`](/reference/items/Action/)'s `data-on:` attribute — either on the same element or on an ancestor. Use the `.stop` modifier to contain them.
| Event | Fired when |
| -------------- | ----------------------------------------------------------------- |
| `timer-start` | the countdown starts (via `start()`, `restart()` or `autostart`). |
| `timer-end` | the countdown reaches zero. |
| `timer-tick` | a cycle completes while `repeat` is enabled (after `timer-end`). |
| `timer-pause` | the countdown is paused. |
| `timer-resume` | a paused countdown resumes. |
| `timer-stop` | the countdown is stopped without completing. |
```html {4}
…
```
### Methods
| Method | Description |
| ----------- | ----------------------------------------------------------------- |
| `start()` | Start — or restart — the countdown from the beginning. |
| `restart()` | Alias for `start()`. |
| `stop()` | Stop the countdown without completing it. |
| `pause()` | Pause the countdown, preserving the remaining time. |
| `resume()` | Resume a paused countdown from where it left off. |
Methods are callable from an `Action` effect when the `Timer` is mounted on the same element:
```html {4}
```
## `TimerProgress`
Extends `Timer` with a continuous progress signal. It inherits every option, event and method above, and adds one event. Mount it in place of `Timer` wherever a smooth indicator is needed; the base `Timer` stays free of the per-frame cost.
### Events
| Event | Detail | Fired when |
| ---------------- | ------------- | ------------------------------------------------------------- |
| `timer-progress` | `[ratio]` | on every animation frame while running — `ratio` goes `0 → 1`, reaches `1` on completion and resets to `0` on `stop()`. |
The ratio is read from `event.detail[0]`:
```html {3}