dxb-count-to/README.md

A vanilla JavaScript counter animation plugin with IntersectionObserver integration

# DXB CountTo

A vanilla JavaScript counter animation plugin with IntersectionObserver integration. This plugin is a replacement for jQuery-based counter plugins, with zero dependencies.

## Features

- Pure vanilla JavaScript (ES2020+)
- Automatic animation when element becomes visible (using IntersectionObserver)
- Customizable animation speed and refresh interval
- Support for formatting options (decimals, thousands separator, prefix, suffix)
- Tiny footprint (~3KB minified)
- No dependencies
- Automatic initialization of new elements added to the DOM via MutationObserver

## Installation

```bash
npm install dxb-count-to
```

## Usage

### Basic Usage

```html
<div class="dxb-countto">
  <div data-from="0" data-to="500">0</div>
</div>

<script>
  // The counters are initialized automatically
  // No manual JavaScript required!
</script>
```

### Advanced Usage

```javascript
import { DXBCountTo, createDXBCountTo } from 'dxb-count-to';

// HTML structure:
// <div class="dxb-countto">
//   <div data-from="0" data-to="1000">0</div>
// </div>

// Initialize with options (if manual initialization is needed)
const counterElement = document.querySelector('.dxb-countto');
const counter = new DXBCountTo(counterElement, {
  from: 0,
  to: 1000,
  speed: 2000,
  refreshInterval: 50,
  decimals: 0,
  seperator: ',',
  prefix: '$',
  postfix: ' USD',
  formatter: function(value, options) {
    return options.prefix + value.toFixed(options.decimals).replace(
      /\B(?=(\d{3})+(?!\d))/g, 
      options.seperator
    ) + options.postfix;
  }
});

// Or use the factory function to create multiple counters at once
const counters = createDXBCountTo('.dxb-countto', {
  speed: 1500,
  seperator: ','
});

// Manually control the counter
counter.start();  // Start counting
counter.stop();   // Pause counting
counter.restart(); // Reset and start over
counter.toggle(); // Toggle between start/stop
counter.destroy(); // Clean up resources
```

## Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| from | Number | 0 | The number to start counting from |
| to | Number | 0 | The number to count up to |
| speed | Number | 1000 | Duration of the animation in milliseconds |
| refreshInterval | Number | 100 | How often the counter is updated in milliseconds |
| decimals | Number | 0 | Number of decimal places to show |
| formatter | Function | null | Function to format the displayed value |
| seperator | String | '' | Character to use as thousands separator |
| prefix | String | '' | Text to display before the number |
| postfix | String | '' | Text to display after the number |
| onUpdate | Function | null | Called each time the counter is updated |
| onComplete | Function | null | Called when the counter finishes |

## Data Attributes Support

You can configure the counter using data attributes on the inner element:

```html
<div class="dxb-countto">
  <div data-from="0" 
      data-to="1000" 
      data-speed="2000" 
      data-refresh-interval="50" 
      data-decimals="0"
      data-seperator="," 
      data-prefix="$" 
      data-postfix=" USD">
    0
  </div>
</div>
```

## Automatic Initialization

DXB CountTo automatically initializes in two ways:

1. **On Page Load**: When the page loads, all elements with the `.dxb-countto` class are automatically initialized.
   
   ```javascript
   // This happens automatically when the script loads
   document.addEventListener('DOMContentLoaded', () => {
     DXBCountTo.initAll(); // Initialize all counters on the page
   });
   ```

2. **Dynamic Content (MutationObserver)**: The plugin uses MutationObserver to detect when new counter elements are added to the DOM and automatically initializes them. This is particularly useful for:
   - Content loaded via AJAX
   - Elements inserted by JavaScript
   - Dynamic UI components

## Element Selection

The plugin targets elements with the `.dxb-countto` class. The structure is:

```html
<div class="dxb-countto">
  <div>0</div> <!-- This inner div will display the counter -->
</div>
```

## Browser Support

Supports all modern browsers that support IntersectionObserver and ES2020+ features.

## License

MIT