> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/timer.md).
# Timer
`avonni-timer`
A timer that lets users measure elapsed time with start, stop, pause and reset controls.
## Overview
**Timer** is a Lightning Web Component that measures elapsed time with start, stop, pause, and reset controls. It can count up from zero or count down from a set duration, and it exposes public methods so you can drive it programmatically.
Use it in your own Lightning Web Components for stopwatches, countdowns, and time tracking. You control the counting direction, the display format, the button set and its position, and optional persistence of the elapsed value to a record field.
### Use Cases
* **Stopwatches:** Count up to measure how long a task takes.
* **Countdowns:** Count down from a duration and stop or repeat at zero.
* **Time tracking:** Save the elapsed time to a record field on stop.
* **Guided steps:** Give users a visible, controllable timer during a process.
* **Programmatic control:** Start, pause, or reset the timer from your own logic.
***
## Variant Guidelines
| Type | Use Case |
| ------------ | ---------------------------------------------- |
| `count-up` | Stopwatch behavior, measuring elapsed time. |
| `count-down` | Countdown from a fixed `duration` toward zero. |
***
## Use Case Examples
### Example 1: Count-up stopwatch
**Scenario:** Show a stopwatch that starts as soon as the component renders.
```html
```
**Result:** A timer that begins counting up immediately, displayed as minutes and seconds.
### Example 2: Programmatic countdown
**Scenario:** Count down five minutes and drive the controls from JavaScript.
```html
```
```js
// breakTimer.js
import { LightningElement } from 'lwc';
export default class BreakTimer extends LightningElement {
startBreak() {
this.template.querySelector('avonni-timer').start();
}
resetBreak() {
this.template.querySelector('avonni-timer').reset();
}
}
```
**Result:** A five-minute countdown with controls beneath it that can also be started and reset in code.
## Specifications
### Attributes
| Name | Description | Type | Default | Required |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ------------ | -------- |
| `auto-save-on-stop` | If present, the timer value is automatically saved to the record field when the timer is stopped. | Boolean | `false` | |
| `auto-start` | If present, the timer automatically starts. | Boolean | `false` | |
| `buttons-position` | Position of the buttons with respect to the timer. Valid values include left, right, top and bottom. | String | `"left"` | |
| `disable-pause-button` | If present, the pause button is disabled. | Boolean | `false` | |
| `display-reset-button` | If present, the reset button is displayed. | Boolean | `false` | |
| `duration` | How long the timer runs in milliseconds. When the duration is reached, the timer stops, or restarts if repeat is present. | Number | `0` | |
| `field-api-name` | API name of the record field the timer value is read from and saved to. | String | — | |
| `interval` | Interval between two timer updates, in milliseconds. | Number | `100` | |
| `label` | Label of the timer. | String | — | |
| `object-api-name` | API name of the object the timer value is read from and saved to. | String | — | |
| `pause-button-icon-name` | The Lightning Design System name of the pause button icon. Names are written in the format 'utility:down' where 'utility' is the category, and 'down' is the specific icon to be displayed. The icon is displayed only when the pause button label is empty. | String | — | |
| `pause-button-label` | Label of the pause button. | String | `"Pause"` | |
| `record-id` | Id of the record the timer value is read from and saved to. | String | — | |
| `repeat` | If present, the timer automatically restarts when it finishes running. | Boolean | `false` | |
| `reset-after-stop` | If present, the timer is reset to its initial value when it is stopped. | Boolean | `false` | |
| `reset-button-icon-name` | The Lightning Design System name of the reset button icon. Names are written in the format 'utility:down' where 'utility' is the category, and 'down' is the specific icon to be displayed. The icon is displayed only when the reset button label is empty. | String | — | |
| `reset-button-label` | Label of the reset button. | String | `"Reset"` | |
| `show-time-labels` | If present, labels are displayed next to the time segments. | Boolean | `false` | |
| `start-button-icon-name` | The Lightning Design System name of the start button icon. Names are written in the format 'utility:down' where 'utility' is the category, and 'down' is the specific icon to be displayed. The icon is displayed only when the start button label is empty. | String | — | |
| `start-button-label` | Label of the start button. | String | `"Start"` | |
| `stop-button-icon-name` | The Lightning Design System name of the stop button icon. Names are written in the format 'utility:down' where 'utility' is the category, and 'down' is the specific icon to be displayed. The icon is displayed only when the stop button label is empty. | String | — | |
| `stop-button-label` | Label of the stop button. | String | `"Stop"` | |
| `time-format` | Format of the timer. Valid values include "hh:flag\_mm:ss", "hh:mm", "mm:ss", "hh", "mm", "ss" and "custom". When set to custom, the format defined by time-format-custom is used. | String | `"hh:mm:ss"` | |
| `time-format-custom` | Custom format of the timer, used when time-format is set to custom. Composed of the tokens "hh", "mm", "ss" and "ms", separated by ":" or ".". For example "mm:ss.ms". | String | — | |
| `time-labels-format` | Format of the time labels. Valid values include short and long. | String | `"short"` | |
| `time-labels-position` | Position of the time labels with respect to the time segments. Valid values include top and bottom. | String | `"top"` | |
| `type` | Type of the timer. Valid values include count-up and count-down. | String | `"count-up"` | |
| `value` | Starting value of the timer in milliseconds. If empty, the value of the record field is used as the starting value. | Number | `0` | |
### Methods
| Name | Description | Argument Name | Argument Type | Argument Description |
| ------- | ---------------- | ------------- | ------------- | -------------------- |
| `pause` | Pause the timer. | | | |
| `reset` | Reset the timer. | | | |
| `start` | Start the timer. | | | |
| `stop` | Stop the timer. | | | |
### Custom Events
#### `pause`
The event fired when the timer is paused.
The `pause` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | --------------------------------------------------------- |
| `value` | number | Elapsed time, in milliseconds, when the timer was paused. |
The event properties are as follows.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `save`
The event fired when the elapsed time is saved to the record, if `record-id` and `field-api-name` are set.
The `save` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `start`
The event fired when the timer is started.
The `start` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `statechange`
The event fired when the timer's state changes.
The `statechange` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | --------------------------------------------------------------------------------------- |
| `state` | string | The new state of the timer. Valid values include idle, in-progress, paused and stopped. |
The event properties are as follows.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `stop`
The event fired when the timer is stopped.
The `stop` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `valuechange`
The event fired when the timer's elapsed time changes.
The `valuechange` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------------- |
| `value` | number | Current elapsed time, in milliseconds. |
The event properties are as follows.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.avonnicomponents.com/lwc-components/core-components/timer.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.