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.

<!-- sessionTimer.html -->
<template>
    <avonni-timer
        label="Session timer"
        type="count-up"
        time-format="mm:ss"
        auto-start
    ></avonni-timer>
</template>

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.

<!-- breakTimer.html -->
<template>
    <avonni-timer
        label="Break"
        type="count-down"
        duration="300000"
        time-format="mm:ss"
        buttons-position="bottom"
    ></avonni-timer>
</template>

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