TURBO for Developers

Home > widget-integration > CountdownTimerController

CountdownTimerController class

Controller that manages the countdown timer widget lifecycle.

Handles the full flow: fetching the active campaign from the API, rendering the timer into the DOM, ticking every second, and handling expiration behavior (repeat, disable, or freeze at 00:00:00).

Signature:

export declare class CountdownTimerController

Example

Extend to add analytics tracking when the timer is displayed:

window.boostWidgetIntegration.extend('CountdownTimerController', (CountdownTimerController) => {
  return class CustomController extends CountdownTimerController {
    async connect(element) {
      await super.connect(element);
      if (element.style.display !== 'none') {
        window.dataLayer?.push({ event: 'countdown_timer_displayed' });
      }
    }
  };
});

Constructors

Constructor	Modifiers	Description
(constructor)(appService, timerAPI, timerService)		Constructs a new instance of the `CountdownTimerController` class

Properties

Property	Modifiers	Type
appService	`protected`	AppService
timerAPI	`protected`	CountdownTimerAPI
timerService	`protected`	CountdownTimerService

Methods

Method	Modifiers	Description
bindEntireBarClick()	`protected`	Bind click and keyboard handlers for the "entire bar clickable" CTA mode. Reads the navigation URL from the `data-timer-cta-link` attribute and attaches `click` and `keydown` (Enter/Space) listeners.
connect(element, scopeOverride)		Initialize the countdown timer on the given DOM element. Fetches the active campaign via the API, then starts the render/tick loop. Hides the element if the API call fails or no campaign matches.
destroy()		Stop the tick interval and release all internal references. Called automatically by . Can also be called directly to clean up without hiding the element.
getTemplate()	`protected`	Retrieve the Liquid template string for the countdown timer.
handleExpired()	`protected`	Handle timer expiration based on the campaign's `onceEnd` setting.
hide()	`protected`	Hide the timer element and destroy the controller.
injectCampaignStyles()	`protected`	Inject campaign-specific CSS (colors, fonts, sizes) via JS.
isSafeUrl(url)	`protected`	Validate that a URL is safe for navigation. Allows `http:`, `https:`, and relative paths. Blocks `javascript:`, `data:`, `vbscript:`, protocol-relative URLs, and any other scheme.
renderAndStartTick()	`protected`	Perform the initial tick and start the 1-second interval loop. Called once after a campaign is successfully fetched. Runs the first `tick()` synchronously (to avoid a 1s blank flash), then sets up `setInterval` for subsequent ticks.
renderTime(time)	`protected`	Render the current time into the DOM via Liquid template. Called once per second by the tick interval. Parses the rendered HTML, replaces the element's children, injects campaign styles, and binds CTA click handlers.
sanitizeCssValue(value)	`protected`	Strip characters that could break out of a CSS value context. Removes `{};<>` and backslashes to prevent CSS injection via merchant-configured style settings.
show()	`protected`	Make the timer element visible by clearing `display: none`.
stopOwnTick()	`protected`	Clear the running `setInterval` tick loop. Called by and before restarting the interval in . Override to cancel additional async work tied to the tick lifecycle.
tick()	`protected`	Single tick: calculate remaining time and render or handle expiration. Runs every second via the interval set by . Delegates to when the timer reaches zero, or otherwise.

← Back to Library Reference