# 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](https://docs.digia.tech/ui-building-blocks/widgets/default-properties "mention"):

**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