# Timer

The **Timer** widget is a time-based utility that lets you run **countdown** or **count-up (stopwatch)** timers inside your app. It can trigger actions at regular intervals (ticks) or when the timer completes, making it ideal for **dynamic, time-driven experiences** like quizzes, games, progress flows, and limited-time offers.

{% embed url="<https://youtu.be/OMoNGjx1r-4?si=YvMBl00aV4IqB5gE>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=OMoNGjx1r-4>

### **Core Concepts**

* **Timer Type**
  * `countDown` – Starts from a given number of seconds and decreases to zero.
  * `countUp` – Starts from a given value (usually 0) and increases over time.
* **Tick**
  * A “tick” is each point in time when the timer updates.
  * Controlled by `updateInterval` (in seconds).
  * On every tick, the widget exposes the **current time value** through `tickValue`.
* **Controller**
  * The `controller` lets you programmatically:
    * **start** the timer
    * **stop/pause** the timer
    * **reset** it back to the initial value
  * These operations can be executed using the **Control Object** action.
  * > **Note:** If a controller is provided, other properties except actions may not work as the timer is controlled programmatically.
  * This is useful when the timer’s behavior depends on user actions or other widgets (e.g., start timer when a quiz question appears).
* **Actions**
  * `onTick` – Runs repeatedly at each interval.
  * `onTimerEnd` – Runs once when the timer finishes (in countDown mode) or when you manually end it.
* **Child & tickValue**
  * The Timer has a `child` slot.
  * Inside this child, you can access **`tickValue`**, which is the **current timer value** (e.g., remaining seconds in a countdown).
  * You can access `tickValue` directly by name or with the widget name prefix: `timerName.tickValue`.
  * This allows flexible referencing and makes it easy to display the timer on-screen without extra state.

### Properties

| Property         | Description                                                                                                                                          |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `controller`     | A TimerController Variable that can be used to control the timer (e.g., start, stop, reset).                                                         |
| `duration`       | The total duration of the timer in seconds.                                                                                                          |
| `initialValue`   | The initial value of the timer. For a countdown timer, this is the number of seconds to count down from. For a stopwatch, this is the starting time. |
| `updateInterval` | The interval in seconds at which the `onTick` action is triggered.                                                                                   |
| `timerType`      | The type of timer. Can be `countDown` or `countUp`.                                                                                                  |
| `onTick`         | An action to be executed at each `updateInterval`.                                                                                                   |
| `onTimerEnd`     | An action to be executed when the timer finishes.                                                                                                    |

#### Events

| Property     | Description                                                                         |
| ------------ | ----------------------------------------------------------------------------------- |
| `onTick`     | Triggered at each `updateInterval`. Receives an object with the current tick value. |
| `onTimerEnd` | Triggered when the timer finishes. Receives an object with the final tick value.    |

***

### Default Properties

The Timer widget supports the following sections of [Default Properties](/ui-building-blocks/widgets/default-properties.md):

**Layout**

* `width`
* `height`
* `padding`
* `margin`

**Alignment**

* `align`

**Visibility**

* `visible`

### **Use Cases**

You can use the Timer widget in scenarios like:

* ⏳ **Countdowns**
  * Quiz timers (e.g., 30 seconds per question)
  * Flash sale or limited-time offer countdowns
  * Session expiry or logout warnings
* ⏱ **Stopwatch / Count-Up**
  * Track how long a user spends on a task or game
  * Measure response times or performance metrics
* 🔁 **Recurring UI Updates**
  * Auto-advancing slides or banners
  * Updating a progress bar every second
  * Periodic API polling (e.g., refresh status every 5 seconds)
* 🎮 **Game & Interaction Logic**
  * Trigger events after a delay (e.g., show hint after 10 seconds)
  * End a level when time runs out
  * Control animations or state changes over time


---

# Agent Instructions: 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:

```
GET https://docs.digia.tech/ui-building-blocks/widgets/input-interaction-widgets/timer.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.