circular-timer-progress-bar

SVG-based circular timer progress bar based. Implemented in native JavaScript. Tested in Google Chrome, Mozilla Firefox, Safari, Microsoft Edge and Opera.

Installation

npm

1npm install --save circular-timer-progress-bar

yarn

1yarn add circular-timer-progress-bar

Examples

Check out a live demo here: https://volkmaster.github.io/circular-timer-progress-bar/

You can use the timer by creating a CircularTimerProgressBar object and calling run function to start the execution. See the documentation for additional information.

React

For more information check out the code in the example folder.

1import { useEffect, useRef } from "react"
2import CircularTimerProgressBar from "circular-timer-progress-bar"
3
4const Example = () => {
5  const progressBarRef = useRef(null)
6
7  useEffect(() => {
8    if (progressBarRef.current) {
9      new CircularTimerProgressBar(
10        {
11          container: progressBarRef.current,
12          widthContainer: 300,
13          heightContainer: 200,
14          strokeWidth: 20,
15          colorContainer: "#5e5e5e",
16          colorCircle: "#c4c3c3",
17          colorPath: "#2c2c2c",
18          colorText: "#2c2c2c",
19          fontFamily: "GothamRounded-Light",
20        },
21        2,
22      ).run(7000)
23    }
24  }, [])
25
26  return <svg ref={progressBarRef} />
27}
28
29export default Example

HTML & Native JS

Every CircularTimerProgressBar class instance needs to be provided with an SVG container object, which functions as a placeholder for other SVG elements:

1<svg id="container"></svg>

1. Timer that runs infinitely:

1const timer = new CircularTimerProgressBar({
2  container: document.getElementById("container"),
3})
4timer.run("inf")

2. Timer that runs for 5 seconds and displays the number of seconds left (color of text changes to alert color with only 2 seconds left) in the middle of the circle with additional options specified (more):

1const timer = new CircularTimerProgressBar({
2  container: document.getElementById("container"),
3  widthContainer: 200,
4  heightContainer: 200,
5  fontFamily: "GothamRounded-Bold",
6})
7timer.run(5000, 2000)

3. Timer that runs for 8 seconds without any text in the middle of the circle with additional options specified (more):

1const timer = new CircularTimerProgressBar(
2  {
3    container: document.getElementById("container"),
4    widthContainer: 250,
5    heightContainer: 350,
6    strokeWidth: 25,
7    colorContainer: "#2c2c2c",
8    colorCircle: "#c4c3c3",
9    colorPath: "#5e5e5e",
10  },
11  0,
12  false,
13)
14timer.run(8000)

4. An example of a timer that runs for 6 seconds with a hidden circle and displaying the number of seconds left (with 1 decimal place; color of text changes to alert color with only 2.5 seconds left) in the middle of the circle with additional options specified (more):

1const timer = new CircularTimerProgressBar(
2  {
3    container: document.getElementById("container"),
4    widthContainer: 150,
5    heightContainer: 150,
6    colorContainer: "#c0c0c0",
7    colorAlert: "#dc143c",
8    fontSize: 50,
9    fontFamily: "GothamRounded-Book",
10  },
11  1,
12  true,
13  false,
14)
15timer.run(6000, 2500)

5. An example of a timer that runs for 7 seconds and displays the number of seconds left (with 2 decimal places) in the middle of the circle with additional options specified (more):

1const timer = new CircularTimerProgressBar(
2  {
3    container: document.getElementById("container"),
4    widthContainer: 300,
5    heightContainer: 200,
6    strokeWidth: 20,
7    colorContainer: "#5e5e5e",
8    colorCircle: "#c4c3c3",
9    colorPath: "#2c2c2c",
10    colorText: "#2c2c2c",
11    fontFamily: "GothamRounded-Light",
12  },
13  2,
14)
15timer.run(7000)

Documentation

The constructor of the CircularTimerProgressBar class initializes the timer.

1CircularTimerProgressBar(options, nDecimals = 0, displayText = true, displayCircle = true)

• options: CircularTimerProgressBarOptions object may contain the following attributes:

  • container: SVGElement: an SVG object, which functions as a placeholder for other SVG elements (required),
  • widthContainer?: number: width of the SVG placeholder in px (optional; default: 300px),
  • heightContainer?: number: height of the SVG placeholder in px (optional; default: 300px),
  • strokeWidth?: number: width of the timer progress bar in px (optional; default: 1/10 of the shortest of the container's dimensions),
  • colorContainer?: string: background color of the placeholder SVG element (optional; default: color inherited from parent),
  • colorCircle?: string: stroke color of the underlying circle SVG element (optional; default: lightgray),
  • colorPath?: string: stroke color of the path SVG element (optional; default: black),
  • colorText?: string: fill color of the text SVG element (optional; default: black),
  • colorAlert?: string: fill color of the text SVG element when time is under 3 seconds (optional; default: red),
  • fontSize?: number: size of the text font in px (optional; default: 1/6 of the shortest of the container's dimensions),
  • fontFamily?: string: font family of the text font (optional; default: sans-serif)

• nDecimals?: number: number of decimals of the text representing the time left (optional; default: 0)

• displayText?: boolean: flag indicating whether the text in the middle of the circle representing the time left (in seconds) is displayed (optional; default: true)

• displayCircle?: boolean: flag indicating whether the circle indicating progress is displayed (optional; default: true)

---

The run function of the CircularTimerProgressBar class start the execution of the timer.

1run(time, alertTime = 0)

• time: number | string: number of milliseconds defining the timer duration (if 'inf', then the timer will be executed for indefinite duration; required)
• alertTime?: number: number of milliseconds defining how much time before the end of the timer should the text in the middle of the circle change its color (optional; default: 0)

---

The pause function of the CircularTimerProgressBar class pauses the execution of the timer.

1pause()

---

The resume function of the CircularTimerProgressBar class resumes the execution of the timer.

1resume()

---

The isRunning function of the CircularTimerProgressBar class tells whether the timer is already running.

1isRunning()

---

The isPaused function of the CircularTimerProgressBar class tells whether the timer is already paused.

1isPaused()

License

MIT © volkmaster