codeplay-timer-js

A high-precision JavaScript timer library designed for games, quizzes, and interactive applications.

codeplay-timer-js provides accurate countdown and count-up timers using requestAnimationFrame and performance.now() to prevent timing drift.

The library includes powerful features like custom time formatting, event triggers, configurable update frequency (tickRate), template rendering, and callbacks.

It is ideal for:

• 🎮 Game timers
• 🧠 Quiz countdowns
• ⏱ Exercise timers
• 🕹 Interactive UI timers
• 📊 Real-time display timers

✨ Features

• ⚡ High precision timer using requestAnimationFrame
• ⏱ Countdown and CountUp timers
• 🎮 Millisecond precision for games
• ⏸ Pause / Resume / Stop controls
• 🔤 Flexible time formatting
• 🧩 Custom format tokens
• 🎨 HTML template rendering
• 🔔 Callback functions
• 🎯 Event triggers (time-based actions)
• ⚙ Configurable update frequency (tickRate)
• 🧠 No timer drift
• 📦 Lightweight and dependency-free

📦 Installation

Install via npm

npm install codeplay-timer-js

or yarn

yarn add codeplay-timer-js

🚀 Basic Usage

import GameTimer from "codeplay-timer-js"

const timer = new GameTimer()

timer.startCountdown({
  start: 10,
  id: "timer",
  format: "MM:SS"
})

HTML:

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

Output:

00:10
00:09
00:08

⏱ Countdown Timer

const timer = new GameTimer()

timer.startCountdown({
  start: 30,
  id: "timer",
  format: "MM:SS",

  onTick(time){
    console.log("Remaining:", time)
  },

  onComplete(){
    console.log("Time finished")
  }
})

⏫ CountUp Timer

timer.startCountUp({
  end: 20,
  id: "timer",
  format: "MM:SS"
})

Counts from 0 → 20 seconds.

♾ Unlimited CountUp

Set end to 0.

timer.startCountUp({
  end: 0,
  id: "timer",
  format: "MM:SS"
})

The timer will run indefinitely.

⏸ Timer Controls

Pause timer

timer.pause()

Resume timer

timer.resume()

Stop timer

timer.stop()

🎨 Template Rendering

You can customize the HTML output.

timer.startCountdown({
  start: 15,
  id: "timer",
  format: "MM:SS",
  template: "<span class='timer'>{time}</span>"
})

Output HTML:

<span class="timer">00:14</span>

⌚ Time Format Options

Supported formats:

| Format | Example | | ------------- | ------------ | | HH:MM:SS | 01:12:30 | | MM:SS | 12:30 | | SS | 30 | | MS | 523 | | HH:MM:SS:MS | 01:12:30:523 |

Example:

format: "HH:MM:SS"

🔤 Custom Format Tokens

You can create fully customized formats.

Supported tokens:

| Token | Meaning | | ------ | ------------ | | {HH} | Hours | | {MM} | Minutes | | {SS} | Seconds | | {MS} | Milliseconds |

Example:

format: "{HH}h {MM}m {SS}s"

Output:

01h 05m 09s

Example with milliseconds:

format: "{MM}:{SS}.{MS}"

Output:

05:21.342

🎯 Event Triggers

You can trigger actions when the timer reaches specific times.

Useful for:

• losing stars
• playing sounds
• warning messages
• changing UI

Example:

timer.startCountUp({

  id: "timer",

  events: {

    5: () => console.log("5 seconds reached"),

    10: () => console.log("10 seconds reached")

  }

})

🎮 Example: Game Star Rating

timer.startCountUp({

  id: "timer",

  events: {

    5: () => updateStars(4),
    7: () => updateStars(3),
    9: () => updateStars(2),
    11: () => updateStars(1),
    15: () => updateStars(0)

  }

})

Example game flow:

0s  ⭐⭐⭐⭐⭐
5s  ⭐⭐⭐⭐
7s  ⭐⭐⭐
9s  ⭐⭐
11s ⭐
15s empty

⚙ tickRate (Update Frequency)

The tickRate option controls how often timer logic updates.

By default, the timer updates once per second for maximum efficiency.

But advanced users can increase the update rate for games or animations.

Default behavior

tickRate: 1

Updates 1 time per second.

Best for:

• countdown timers
• quizzes
• UI timers

High precision mode

tickRate: 60

Updates 60 times per second.

Best for:

• game timers
• animations
• millisecond display

Example

timer.startCountUp({
  id: "timer",
  format: "MM:SS:MS",
  tickRate: 60
})

📊 tickRate Performance

| tickRate | Updates per second | Use case | | -------- | ------------------ | -------------- | | 1 | 1 | Normal timers | | 10 | 10 | Smooth UI | | 60 | 60 | Game precision |

Even with higher tick rates, the timer remains efficient because it uses requestAnimationFrame.

🧠 Configuration Options

All timer options are passed via an object.

| Option | Type | Description | | ------------ | -------- | --------------------------------- | | start | number | Countdown start time (seconds) | | end | number | CountUp target time (seconds) | | id | string | HTML element ID for rendering | | format | string | Time display format | | template | string | HTML template containing {time} | | events | object | Time-based event triggers | | tickRate | number | Update frequency per second | | onTick | function | Runs on every tick | | onComplete | function | Runs when timer ends |

📂 Browser Usage (CDN)

<script src="https://unpkg.com/codeplay-timer-js/dist/codeplay-timer.umd.cjs"></script>

⚙ How It Works

Unlike traditional timers using setInterval, this library uses:

• requestAnimationFrame
• performance.now()

Benefits:

• accurate timing
• smooth updates
• no timer drift

Perfect for games and real-time interfaces.

🛠 Use Cases

• Game countdown timers
• Quiz timers
• Exercise timers
• Pomodoro timers
• Auction countdowns
• Event timers
• Animation timing

🤝 Contributing

Contributions are welcome.

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

📄 License

MIT License

Copyright © CodePlay

⭐ Support

If you find this project useful, please consider starring the repository.

Made with ❤️ by CodePlay