canvas-circular-countdown

Draw a configurable circular canvas countdown timer.

Check here for a live demo.

NOTE: Depends on window.requestAnimationFrame. If your environment does not support it, you can polyfill.

Install

$ npm install canvas-circular-countdown --save

Usage

The library is exported in UMD, CommonJS, and ESM formats. You can import it the following ways:

Using ESM import statement

import CanvasCircularCountdown from 'canvas-circular-countdown';

Using CommonJS require statement

const CanvasCircularCountdown = require('canvas-circular-countdown').default;

Old school browser global

<script src="https://unpkg.com/canvas-circular-countdown"></script>

API

Instantiation

new CanvasCircularCountdown(element, [options], [onTimerRunning])

Param	Type	Description
element	HTMLElement	(Required) The element that the countdown is drawn to. If is a canvas element, the countdown will be drawn on it; otherwise a canvas element will be created and appended to element.
options	Object	(Optional) Options that can be overriden by user. See below for more details about each option.
onTimerRunning	Function	(Optional) Function to be executed while timer is running. Parameters passed by include the percentage remaining, an object containing the remaining and elapsed time and the CanvasCircularCountdown instance.

Options

Param	Type	Default	Description
duration	Number	60 * 1000	The timer's duration in milliseconds. Throws TypeError if the provided value is not a Number or is NaN.
elapsedTime	Number	0	The time that has elapsed in milliseconds. Throws TypeError if the provided value is not a Number or is NaN.
throttle	Number	undefined	Throttle duration in milliseconds. Must be a number lower or equal to the duration option. If provided, it limits the number of times the canvas is drawn in the given period, therefore the number of times the callback function onTimerRunning can be called. You can use it if you perform heavy tasks inside the onTimerRunning callback function to improve performance. Always prefer small numbers, eg. 250, etc
clockwise	Boolean	false	Determines the direction of the progress ring. By default the direction is counterclockwise.
radius	Number	150	The radius of the circular countdown in pixels.
progressBarWidth	Number	15	The circular progress bar in pixels.
progressBarOffset	Number	5	The number of pixels that will be left between the edges of the progress bar and the rest of the circle.
circleBackgroundColor	String	"#ffffff"	The background color of the main circle.
emptyProgressBarBackgroundColor	String	"#dddddd"	The background color of the progress bar when is empty.
filledProgressBarBackgroundColor 1	String|Function	"#00bfeb"	The background color of the progress bar when is filled.
captionText 1	String|Function	undefined	The text to be displayed as caption inside the countdown circle. By default if it is left as undefined and showCaption is set to true, the remaining percentage will be displayed.
captionColor 1	String|Function	"#343a40"	The foreground color of the caption string.
captionFont 1	String|Function	"20px sans-serif"	The text style of the caption string. Check here for available values.
showCaption 1	Boolean|Function	true	Whether the caption text inside the countdown circle will be displayed or not.
draw	Function	undefined	A function that exposes CanvasRenderingContext2D to allow free drawing on the canvas element. The function is called with 2 arguments. The first argument is the CanvasRenderingContext2D and the second is an object with information like the canvas width/height, the remaining percentage and an object containing the remaining and elapsed time.

¹ If it is a function, the remaining percentage and an object containing the remaining and elapsed time are passed as parameters and it should return the appropriate type for each option. For example, for showCaption should return a boolean (true or false), but for captionColor should return a string. Useful when you need to change some options' values depending on the remaining percentage or the remaining/elapsed time.

Instance methods

start()

Start the timer. If the timer has been already started, the timer will just resume.

start() => CanvasCircularCountdown

stop()

Stop/Pause the timer.

stop() => CanvasCircularCountdown

reset()

Resets the timer to initial specified duration extracting the elapsedTime if provided.

reset() => CanvasCircularCountdown

style(options = {})

Change the styles of the circular countdown at any time while te timer running.

Param	Type	Default	Description
options	Object	{}	Any of the options provided above can be changed apart from the duration, elapsedTime and throttle options.

style(options = {}) => CanvasCircularCountdown

setDuration(time)

Set the timer's duration (in milliseconds), at any time, even when the timer is running.

Param	Type	Default	Description
time	Number	-	The timer's duration in milliseconds. Throws TypeError if the provided value is not a Number or is NaN.

setDuration(time) => CanvasCircularCountdown

setElapsedTime(time)

Set the timer's elapsed time (in milliseconds), at any time, even when the timer is running.

Param	Type	Default	Description
time	Number	-	The timer's elapsed time in milliseconds. Throws TypeError if the provided value is not a Number or is NaN.

setElapsedTime(time) => CanvasCircularCountdown

Examples

Example 1 - Default configuration

Create a new instance of CanvasCircularCountdown with the default configuration and immediately start the countdown timer. Pause the countdown after 5 seconds have passed.

HTML

<canvas id="countdown-canvas"></canvas>

JavaScript

new CanvasCircularCountdown(document.getElementById('countdown-canvas'), (percentage, time, instance) => {
  if (time.elapsed >= 5000) {
    instance.stop();
  }
}).start();

Example 2 - Custom configuration

Same as the above example, but with custom configuration.

HTML

<canvas id="countdown-canvas"></canvas>

JavaScript

new CanvasCircularCountdown(document.getElementById('countdown-canvas'), {
  duration: 30 * 1000,
  radius: 200,
  progressBarWidth: 20,
  progressBarOffset: 0,
  circleBackgroundColor: '#f5f5f5',
  emptyProgressBarBackgroundColor: '#b9c1c7',
  filledProgressBarBackgroundColor: '#17a2b8',
  captionColor: '#6c757d',
  captionFont: '22px serif',
  showCaption: true
}, (percentage, time, instance) => {
  if (time.elapsed >= 5000 ) {
    instance.stop();
  }
}).start();

Example 3 - Change progress bar and caption string color depending on percentage remaining

HTML

<canvas id="countdown-canvas"></canvas>

JavaScript

const pickColorByPercentage = (percentage, time) => {
  switch (true) {
    case percentage >= 75:
      return '#28a745'; // green
    case percentage >= 50 && percentage < 75:
      return '#17a2b8'; // blue
    case percentage >= 25 && percentage < 50:
      return '#ffc107'; // orange
    default:
      return '#dc3545'; // red
  }
}

new CanvasCircularCountdown(document.getElementById('countdown-canvas'), {
  filledProgressBarBackgroundColor: pickColorByPercentage,
  captionColor: pickColorByPercentage
}).start();

Example 4 - Responsive canvas

HTML

<div id="countdown-container">
  <canvas id="countdown-canvas"></canvas>
</div>

CSS

#countdown-container {
  width: 100%;
  max-width: 500px;
}

JavaScript

const containerEl = document.getElementById('countdown-container');
const countdownEl = document.getElementById('countdown-canvas');

const countdown = new CanvasCircularCountdown(countdownEl, {
  radius: containerEl.getBoundingClientRect().width / 2
}).start();

let resizeTimeout;

window.addEventListener('resize', () => {
  clearTimeout(resizeTimeout);

  resizeTimeout = setTimeout(() => {
    countdownEl.style({
      radius: containerEl.getBoundingClientRect().width / 2
    });
  }, 250);

Example 5 - Change caption text depending on percentage

HTML

<canvas id="countdown-canvas"></canvas>

JavaScript

new CanvasCircularCountdown(document.getElementById('countdown-canvas'), {
  captionText: percentage => {
    if (percentage <= 25) {
      return 'Time is running out!';
    }

    return 'There is time. Don\'t worry!';
  }
}).start();

Example 6 - Free draw on canvas element

HTML

<canvas id="countdown-canvas"></canvas>

JavaScript

new CanvasCircularCountdown(document.getElementById('countdown-canvas'), {
  draw: (ctx, opts) => {
    // Draw a in the centre of the canvas element,
    // with radius being 1/4 of the canvas width.
    ctx.save();
    ctx.beginPath();
    ctx.arc(opts.width / 2, opts.height / 2, opts.width / 4, 0, 4 * Math.PI, false);
    ctx.lineWidth = 5;
    ctx.strokeStyle = opts.percentage >= 50 ? '#008000' : '#ff0000'; // change color according to percentage
    ctx.stroke();
    ctx.restore();
  }
}).start();

License

The MIT License (MIT)