/canvas-circular-countdown

Draw a configurable circular canvas countdown timer.

Primary LanguageJavaScriptMIT LicenseMIT

npm version License: MIT

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

1 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() => CanvasCircularCountdown

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

stop() => CanvasCircularCountdown

Stop/Pause the timer.

reset() => CanvasCircularCountdown

Resets the timer to initial specified duration.

style(options = {}) => CanvasCircularCountdown

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 and throttle options.

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)