custom-countdown

A simple and customizable React circular countdown

Usage no npm install needed!

<script type="module">
  import customCountdown from 'https://cdn.skypack.dev/custom-countdown';
</script>

README

Build Status Coverage Status

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.

Basic example Stylized example Formatter example

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