@bva/countdown

BVA Countdown Timer

This is a JS based component for adding countdown timers using data attributes and minimal JS.

Installing

yarn add @bva/countdown to install, and then import with import Timer from '@bva/countdown';

Using the Component

Parameters

At the moment there is only one (very optional) parameter (passed in an object):

• errorCallback (function): Only used for timers that are lazy loaded in when on a browser not supporting Intersection Observeres. Default callback will just start the timer.

Data Attributes

This is how the component does most of its configuration. There are a couple of data attributes that can be added to timers to change how they operate:

• data-timer: this signifies that an element is a timer. It should have a value equal to the number of seconds on the timer.
• data-timer-format: this is how the time left should be displayed in the timer. It is a string and can take the following special characters (note that if any of the values are lowercase, they will print no leading zeros - defaults to %D:%H:%M:%S):
  • %D - the number of days left for the countdown.
  • %H - the number of hours left for the countdown.
  • %M - the number of minutes left for the countdown.
  • %S - the number of seconds left for the countdown.
• data-complete-message: this is the message to insert in the timer element once the countdown ends. Not adding will result in the timer displaying a time of '0' in the format specified.
• data-lazy-timer: this denotes that the timer should not start until the timer element comes into the viewport.
• data-pause-timer: this denotes that the timer should pause when it leaves the viewport.

Events

The component introduces a custom event as well:

• countdownTimerEnded: this is bound directly to timer elements and is dispatched when the timer's countdown ends.

Example

<!-- HTML -->

<div class="my-timer"
     data-timer="3600"
     data-timer-format="%M:%H"
     data-complete-message="Time's up!"
     data-lazy-timer
     data-pause-timer>
</div>

// JavaScript

import Timer from '@bva/countdown';

document.addEventListener('DOMContentLoaded', () => {
	// add event listeners to the timer elements
	const timerElements = document.querySelectorAll('[data-timer]');
	timerElements.forEach((timerElement) => {
		timerElement.addEventListener('countdownTimerEnded', (event) => {
			console.log('Timer has ended for:', event.target);
		});
	});
	
	// now setup all the timers to start their countdowns 
	Timer.setup({});
});

Additional Methods

There are two other methods the component exposes for more manual control over timers:

• startTimer: takes in the timer element as a parameter and will start the timer for that timer element.
• pauseTimer: takes in the timer element as a parameter and will stop the timer for that timer element.

Here is an example for the two methods:

import Timer from '@bva/countdown';

document.addEventListener('DOMContentLoaded', () => {
	// Assuming there is only one timer on the page I care about
	const myTimer = document.querySelector('[data-timer]');
	Timer.startTimer(myTimer);
	
	const stopButton = document.querySelector('[data-stop-button]');
	stopButton.addEventListener('click', () => {
		Timer.pauseTimer(myTimer)
	});
});