durations.js - JavaScript animated durations library

Basic Info

A animated durations library built to provide convenience for developers.

If you like the smooth scrolling functionality found here you may like our scrolls.js smooth scrolling library!

Features

Plug-and-play (unless you have other JavaScript that uses durations() already...)
Selector-based targeting
Allows a function to be called when an animated duration has started and/or ended
Customizeable before start and after end text
Customizeable before duration and after duration text
Customizeable start and end dates, of course
Fully open source

Getting Started

Installation

You can install the libaray via npm:

npm i durations.js

or via CDN:

<!-- Source Version -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/durations.js"></script>

<!-- Minified Version -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/durations.min.js"></script>

Usage

// Initialize a duration
durations('h2', {
  date: 'July 27, 2018 12:00:00 (EST)',
  text: 'Coming Soon!'
}, {
  date: 'July 28, 2018 12:00:00 (EST)',
  text: 'The launch is over!'
}, true);

Examples

Time since January 1st, 1970 (UTC)

HTML:

<p class="js-duration-since">Loading...</p>

JS:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/durations.min.js"></script>
<script>
durations('.js-duration-since',{
  date: 0
},{
  afterText: ' since the beginning of JS time.',
  beforeText: 'There has been ',
  date: 0
}, false);
</script>

Time until December 31st, 9999

HTML:

<p class="js-duration-until">Loading...</p>

JS:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/durations.min.js"></script>
<script>
durations('.js-duration-until',{
  afterText: ' until December 31st, 9999.',
  beforeText: 'There are ',
  date: 'July 28, 2018 12:00:00 (EST)'
},{
  date: 'Dec 31, 9999',
  text: 'The event has ended.'
}, true);
</script>

Documentation

/**
 * Animates a duration change among two dates based on the current time.
 * 
 * @param {String} selector - Element(s) to add the duration message
 * @param {Object} start - Object of start date, before text, after text, text
 *                         to display if before the start date, and a callback
 *                         function to execute when animated duration starts
 * @param {Object} end - Object of end date, before text, after text, text to
 *                       display when past the end date, and a callback function
 *                       to execute when the end date has been passed
 * @param {Boolean} stop - Whether duration should stop or not, if not then it
 *                         will continue counting without ever displaying the
 *                         end text
 */

// selector would be any DOM selector you wish, on our landing page we use
// ".js-duration". The selector value must be supplied.

// start object can be as follows but should at least include a start date.
// Defautls to displaying the duration and if before the start date of 
// July 30, 2018 12:00:00 (EST) it will display "Coming Soon!".

{
  afterText: ' until the event occurs.',
  beforeText: 'There are ',
  callback: () => {
    return navigator.sendBeacon('/api/log', { start: true });
  },
  date: 'July 27, 2018 12:00:00 (EST)',
  text: 'The new event is coming soon!!'
}

// end object can be as follows but should at least include an end date.
// Defaults to displaying the duration and when past the text
// "Event has passed.".

{
  afterText: ' since the event occurred.',
  beforeText: 'There have been ',
  callback: () => {
    return navigator.sendBeacon('/api/log', { end: true });
  },
  date: 'July 28, 2018 12:00:00 (EST)',
  text: 'The event has ended.'
}

// stop boolean tells the function whether or not it should continue counting
// after the end date has passed, possibly so you can let people know how much
// time has passed since the event. Defaults to true.

true

// Putting it together now!

durations('.js-duration',{
  afterText: ' until the event occurs.',
  beforeText: 'There are ',
  callback: () => {
    return navigator.sendBeacon('/api/log', { start: true });
  },
  date: 'July 27, 2018 12:00:00 (EST)',
  text: 'The new event is coming soon!!'
},{
  afterText: ' since the event occurred.',
  beforeText: 'There have been ',
  callback: () => {
    return navigator.sendBeacon('/api/log', { end: true });
  },
  date: 'July 28, 2018 12:00:00 (EST)',
  text: 'The event has ended.'
}, true);

Changelog

Please see CHANGELOG.md for details.

License

MIT