flip-second-counter

A lightweight flip-clock style seconds countdown counter (up to 60 seconds) in pure JavaScript. No dependencies. Works standalone, with jQuery, or bundled via npm. CSS is injected automatically — no separate stylesheet import needed.

Install

npm install flip-second-counter

Or use directly via a <script> tag:

<script src="node_modules/flip-second-counter/src/flip-counter.js"></script>

Usage

Pure JavaScript

<div id="timer"></div>

<script>
  var counter = new FlipCounter('#timer', {
    time: 30,                 // seconds (0 - 60 max)
    size: 60,                 // digit height in px
    color: '#fff',            // digit text color
    backgroundColor: '#9F4636' // digit card background
  });
</script>

Designs

By default the counter renders as flip-clock cards. Pass design to switch the look — all other options work the same in every design:

new FlipCounter('#timer', { design: 'circle', time: 30 });

// React
<FlipCounter design="circle" time={30} />

| design | Look | | ----------- | ----------------------------------------------------------------------- | | 'flip' | Flip-clock cards (default). Shows two digits (05). | | 'circle' | Count inside a circle; a ring starts at 12 o'clock and depletes clockwise in real time — exactly empty at 0. | | 'bar' | Count above a horizontal progress bar that depletes in real time. | | 'digital' | LED / digital-clock style display with a glow and ghost segments (05). |

Color mapping per design: color is always the count text (and LED glow); backgroundColor is the flip card, the circle + ring, the bar fill, or the digital panel. An unknown design value safely falls back to 'flip'.

With jQuery

$('#timer').flipCounter({ time: 45, size: 50, color: '#ccc', backgroundColor: '#333' });

With a bundler (webpack / vite / etc.)

import FlipCounter from 'flip-second-counter';

new FlipCounter(document.getElementById('timer'), { time: 60 });

With React

import FlipCounter from 'flip-second-counter/react';

function App() {
  return (
    <FlipCounter
      time={30}
      size={60}
      color="#fff"
      backgroundColor="#9F4636"
      onComplete={() => alert('Time up!')}
    />
  );
}

The React wrapper accepts all the options below as props, plus className and style for the wrapper <div>. Requires React 16.8+ (hooks).

Prop behavior:

• Changing time, autoStart or design recreates the counter (countdown restarts).
• Changing size / color / backgroundColor updates styles in place without resetting the countdown.
• onTick / onComplete always call the latest callback you passed — inline closures over state are safe.

You can control the counter through a ref:

const ref = useRef(null);

<FlipCounter ref={ref} time={30} autoStart={false} />
<button onClick={() => ref.current.start()}>Start</button>
<button onClick={() => ref.current.stop()}>Stop</button>
// also available: reset(time?), setTime(time), getTime(), getInstance()

TypeScript definitions are included for both entry points.

Options (props)

| Option | Type | Default | Description | | ----------------- | -------- | ----------- | ---------------------------------------------- | | design | string | 'flip' | 'flip', 'circle', 'bar' or 'digital' — see Designs. | | time | number | 60 | Countdown seconds. Clamped to 0–60. | | size | number | 50 | Base size in px. Flip: digit height. Circle: container is 1.5 × size. Bar: width is 3 × size. Digital: font is 0.8 × size. | | color | string | #ccc | Digit text color. | | backgroundColor | string | #9F4636 | Digit card background color. | | autoStart | boolean | true | Start counting immediately. | | onTick | function | null | Called every second with remaining seconds. | | onComplete | function | null | Called when the countdown reaches 0. |

Methods

counter.start();      // start / resume
counter.stop();       // pause
counter.reset();      // back to initial time (stopped)
counter.reset(20);    // reset with a new time
counter.setTime(45);  // reset + restart with new time
counter.getTime();    // remaining seconds
counter.setStyle({ color: '#fff', backgroundColor: '#333', size: 60 });
                      // change look without resetting the countdown
counter.destroy();    // remove everything from the element

Demo

The demo/ folder lives in the source repository (it is not shipped in the npm package). Clone the repo and open demo/index.html in a browser, or run npm run demo from the repo root.

Roadmap

• Phase 1 (current): seconds-only countdown, max 60s
• Phase 2: minutes + seconds
• Phase 3: hours support, count-up mode

License

MIT