react-countdown360

A simple and customizable React circular countdown that counts down a number of seconds. This is a React implementation of John Schult's original jquery.countdown360

Examples

You can find some examples in the examples directory.

Quickstart

Install with npm:

npm install react-countdown360

Render your countdown:

import Countdown360 from 'react-countdown360'

const App = () => {
  return <Countdown360 seconds={10} />
}

Documentation

Props

Name	Type	Default	Description
seconds	Number	-	Number of seconds for the countdown
autoStart	Boolean	true	Start the countdown immediatly after rendering
backgroundColor	String	'#fff'	Color for the center of the circle
borderFillColor	String	'#f11'	Color for the filled part of the border
borderUnfillColor	String	'#e6e2e7'	Color for the unfilled part of the border
borderWidth	Number	20	Width in pixels of the border
clockwise	Boolean	false	Select the direction of rotation you prefer
fontColor	String	'#111'	Font color for the label
fontFamily	String	'sans-serif'	The font to use for the label
fontSize	Number	45	Font size in pixels
fontWeight	Number	700	Font weight for the label
onComplete	Function	undefined	A callback called when the countdown is over
smooth	Boolean	false	Update the border once every second or smoothly
startingAngle	Number	0	The angle at which the countdown should start
timeFormatter	Func	timeFormatterSeconds	A function that returns the value to display
unitFormatter	Func	unitFormatterSeconds	A function that returns the unit to display
width	Number	200	Width in pixels of the countdown to render

Time Formatters

You can customize the way the value on the countdown is shown by providing a custom timeFormatter function.

By default, the value shown is the number of seconds remaining rounded to the nearest integer.

A time formatter is a function that takes one single argument, being the number of milliseconds left, and returns the value to show on the countdown.

For instance, the following function is a time formatter that always shows a value with at least two digits:

const timeFormatterTwoDigits = timeLeft => {
  return Math.round(timeLeft / 1000).toString().padStart(2, '0')
}

We already provide a few time formatters that you can import from the package.

Name	Description	Examples	Suggested unit formatter
timeFormatterSeconds	Rounded number of seconds (default behaviour)	0, 1, 12	unitFormatterSeconds
timeFormatterDigitalClock	MM:SS	00:00, 00:12, 01: 59	unitFormatterBlank

Unit Formatters

You can also customize the unit shown on the countdown by providing a custom unitFormatter function.

A unit formatter is a function that takes one single argument, being the value shown on the countdown (as returned by the given time formatter), and returns the unit to display.

For instance, the following function is a unit formatter to show the number of seconds in Spanish:

const unitFormatterSpanishSeconds = value => {
  return value.toString() === '1' ? 'segundo' : 'segundos'
}

Be careful when choosing your unit formatter that it matches the time formatter in use!

We already provide a few unit formatters that you can import from the package.

Name	Description	Examples
unitFormatterSeconds	'second' or 'seconds'	second, seconds
unitFormatterBlank	An empty string

Methods

• start: start or resume the countdown
• stop: pause the countdown
• addSeconds (Number): add or remove (if negative) the given number of seconds to remaining number of seconds
• extendTimer (Number): add or remove (if negative) the given number of seconds to the total number of seconds