rollex v1.0.0-rc.9

Rollex

Versatile counters in React

Installation

Install with yarn:

yarn add rollex
# or npm:
npm i -S rollex

Usage

1. Import Counter component:

import { Counter } from 'rollex'

2. Use it:

<Counter seconds={98} />

API

Setting time intervals

There are multiple ways of setting the time interval to count down (or up) to:

You can tell Rollex how many seconds to count:

<Counter seconds={60} />

Or, you can specify timestamps to count to (and from):

// from now to a given timestamp
<Counter to={1506951918155} />
// from `from` to `to`
<Counter from={1506951900123} to={1506951918155} />

Update interval

By default, Rollex counters update every second. You can, however, set your own update period via interval prop:

// update every 2 seconds
<Counter seconds={60} interval={2000} />

Countdown direction

By default, Rollex counters count "down" (from, say, 60 down to 0). You can make a counter go up:

// from 0 to 60
<Counter seconds={60} direction="up" />

Periods and segments

Rollex counters are split into periods (days, hours, minutes, seconds). Each period has its own segment, which contains the digits which correspond to a given period.

By default, Rollex counters use four periods: "days", "hours", "minutes", "seconds" and each segment is exactly 2 digits long.

You can control this behaviour:

// show only hours and minutes
<Counter seconds={3600} minPeriod="minutes" maxPeriod="hours" />
// show 3 digits per segment
<Counter seconds={72 * 3600} digits={3} />

Freezing the countdown

You can temporarily (or not) freeze the counter by passing it a frozen prop:

<Counter seconds={60} frozen />

When frozen is truthy, the counter will not update at all.

Synchronizing time with client

By default, Rollex counters do not try to synchronize time. That means that if a counter is frozen at 59 seconds, and then unfrozen after an hour, it will continue counting down from 59 seconds. If time sync is enabled, the counter will synchronize time and instantly go down to 0.

<Counter seconds={59} syncTime />

Animating the counter

By default, Rollex counters are not animated (they look like digital clocks). If you want to enable animations (make the counters look analog), you should pass the easingFunction prop (any valid CSS easing function):

<Counter seconds={59} easingFunction='ease-in-out' />

You can also control animation duration (300 ms by default):

<Counter seconds={59} easingFunction='ease-in-out' easingDuration={500} />

Radix

You can even control the radix that Rollex counters use! By default it's 10, but if you want to go dozenal, you can:

<Counter seconds={3600} radix={12} />

Transform and wrap digits

If you want to use different symbols for your digits, you can (let's say, you want a dozenal counter with 'X' representing a 10 and 'E' representing an 11):

<Counter seconds={3600} radix={12} digitMap={{
  'A': 'X',
  'B': 'E',
}} />

You can get even more control over your digits with a digit map:

// use images instead of text for digits
<Counter
  seconds={3600}
  digitWrapper={digit => <img src={`/digits/${digit}.jpg`} />}
/>

Labels and separators

All counter segments can be labelled.

// map from periods to strings
<Counter seconds={141234} labels={{
  days: 'days',
  hours: 'hours'
}} />
// use a function (use case: pluralisation)
<Counter seconds={123123} labels={(period, number) => {
  return number % 10 === 1 ? period.slice(0, -1) : period
}}>

Segments can be separated by a separator symbol:

// dd:hh:mm:ss
<Counter seconds={2312413} separator=':' />