TmOdometer  

TmOdometer is a lightweight JavaScript library for creating animated numeric counters with smooth transitions and precise decimal handling. It is ideal for projects requiring dynamic number animations.

Table of Contents

1. Project Overview
2. Features
3. Screenshots
4. Environment Setup
- Prerequisites
- Setup Steps
5. Usage
- How to Use
- Configuration
- Demos
6. Development
- Setup for Development
7. Acknowledgments
8. Extras
- Angular Version
9. Support
10. License

Project Overview

TmOdometer is inspired by and built on top of HubSpot's Odometer library. It enhances the original functionality by introducing modern TypeScript and ES Module support, along with precise decimal handling to ensure numbers with decimal places retain their accuracy during and after animations (e.g., 1200 with a precision of 2 will display as 1200.00). Designed for seamless integration into any JavaScript or TypeScript project, it works effortlessly with modern module systems and bundlers.

While TmOdometer is a fully standalone library, it is also used as the foundation for the Angular version, TmNgOdometer, which provides seamless integration with Angular applications.

Features

- Lightweight: Minimal dependencies and optimized for performance.
- TypeScript Support: Fully rewritten in TypeScript, the library provides type safety, an enhanced developer experience, and automatically generated type definitions.
- Flexible Integration: Works natively with ES Modules, CommonJS, AMD, and UMD bundles.
- Decimal Precision: Preserves decimal precision during animations.
- Customizable Themes: Supports various themes and animation styles.
- Dynamic Updates: Easily update values programmatically to trigger animations.

Screenshots

See the TmOdometer in action below:

!Quick Preview 1

> _A quick look at the TmOdometer in action._

---

$3



> _Click to watch the high-quality video with smooth animations and detailed UI/UX._

Environment Setup

$3

- Node.js/NPM

$3

1. Install the library via npm:

``bash
npm install tm-odometer --save
`

2. Include one or more themes

`html
rel="stylesheet"
href="node_modules/tm-odometer/themes/odometer-theme-default.css"
/>
`

> Tip: Replace 'default' in the file path with any of the available themes: 'car', 'digital', 'minimal', 'plaza', 'slot-machine', 'train-station'.

3. Import the library using one of the following methods:

- ES Modules:

`javascript
import TmOdometer from 'tm-odometer';
`

> Tip: If using TypeScript, types are directly provided with the library bundle.

- CommonJS:

`javascript
const TmOdometer = require('tm-odometer');
`

- AMD:

`javascript
require.config({
baseUrl: './src',
paths: {
'tm-odometer': 'node_modules/tm-odometer/umd/tm-odometer',
},
});
define(['tm-odometer'], function (TmOdometer) {});
`

- Direct Inclusion

`html

`

Usage

$3

#### Use the Library Programmatically

Once the library is imported, you can use it as follows:

`javascript
const odometer = new TmOdometer({
el: document.getElementById('odometer-element'),
value: 1000,
animation: 'count',
duration: 2000,
format: '(,ddd).dd',
theme: 'default',
});

// Update the value programmatically
odometer.update(2000);
`

> Tip: When included directly, the legacy Odometer constructor is also available for backward compatibility with older versions.

#### Add Odometer to an Element

Another way to use the library is to add the odometer class to any element in your HTML:

`html



`

Update the value programmatically:

`javascript
document.querySelector('.odometer').innerHTML = 456;

// or

document.querySelector('.odometer').odometer.update(456);
`

$3

The library supports the following configuration options:

| Option | Type | Default | Description |
| ----------- | ------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| el | HTMLElement | null | The DOM element where the odometer will be rendered. |
| value | number | 0 | The initial value of the odometer. |
| animation | string | 'slide' | Animation effect type. Options: 'slide', 'count'. |
| duration | number | 2000 (ms) | Duration of the animation in milliseconds. |
| format | string | '(,ddd).dd' | Number format. Examples: '(,ddd)' → 12,345, '(,ddd).dd' → 12,345.67, (.ddd),dd → 12.345,67. |
| theme | string | 'default' | Theme for the odometer. Options: 'default', 'car', 'digital', 'minimal', 'plaza', 'slot-machine', 'train-station'. |

#### Global Configuration

You can configure all odometer instances globally by defining the window.odometerOptions object before including or importing the tm-odometer library:

`html


`

$3

If you need to configure a single odometer instance differently from the global configuration, you can initialize it programmatically using the TmOdometer constructor:

`html



`

$3

To help you get started, TmOdometer includes a comprehensive set of demos showcasing its usage with different module formats (CJS, ESM, UMD, AMD, and legacy). Each demo is a self-contained project that you can run locally.

#### Available Demos

| Demo | Description |
| --------------- | --------------------------------------------------------------------------- |
| ESM | Demonstrates usage with native ES Modules in modern browsers. |
| CJS | Demonstrates usage with CommonJS in bundlers such as Webpack or ESBuild. |
| UMD Browser | Demonstrates usage with UMD bundles directly in the browser via