sa-counter

sa-counter is a flexible Angular directive to increment or decrement a number in an HTML element when it comes into view. It offers options for controlling speed, maximum value, extra text, and countdown functionality.

Installation

Install the package using npm:

npm install sa-counter

Import the Directive

To use the directive in your Angular component, import it like so:

import { CounterDirective } from "sa-counter";

Usage

Add the counter directive to any HTML element to start the increment or decrement process when the element enters the viewport.

Inputs

• @Input() counter: any = 0;
  The actual number you want to increment or decrement to.

  <div [counter]="500"></div>

• @Input() max: any = 1; Defines the maximum value to help synchronize multiple increments. Ensures grouped elements finish at the same time. If all number less than 300 specify the max number to finish at the same time.

  <div [counter]="120" [max]="290"></div>
  <div [counter]="33" [max]="290"></div>
  <div [counter]="234" [max]="290"></div>
  <div [counter]="290" [max]="290"></div>

• @Input() speed: number = 2000; Controls the speed of the increment or decrement (By ms).

  <div [counter]="3023" [speed]="1000"></div>
  <div [counter]="4023" [speed]="1000"></div>

• @Input() extra?: string; Any extra string to display before the number (e.g., "+").

  <div [counter]="3023" extra="$"></div>

  Output will be $3022

• @Input() delay: number = 0; Delays the start of the increment/decrement process by the specified time in milliseconds.

  <div [counter]="234"></div>
  <div [counter]="222" [delay]="300"></div>

• @Input() reverse: boolean = false; If true, the number will count down from the specified counter value to 0.

  <div [counter]="234"></div>
  <div [counter]="222" [reverse]="true"></div>

• @Input() format?: (value: number) => string; A custom function to format the number (e.g., to add two digit).

  in ts file

  transformer(number: number):string {
    return number.toFixed(2);
  }

  <div [counter]="234" [format]="transformer"></div>

  Output will be 234.00

• @Input() resetOnScrollOut: boolean = false; If true, the counter will reset when the element scrolls out of view, allowing the animation to restart when it comes back into view.

• @Input() offset:number = 100; Defines the distance in pixels before the element enters the viewport to start the counter.

Outputs

• @Output() completed = new EventEmitter<any>(); Emits an event when the increment or decrement completes.
• @Output() started = new EventEmitter<any>(); Emits an event when the increment or decrement starts.

Example

<!-- Increment example -->
<div [counter]="500" [max]="1000" [speed]="30" extra="+"></div>
<!-- Decrement example -->
<div [counter]="500" [reverse]="true" [speed]="30"></div>

In the first example, the element will count up to 500 with a "+500" label once completed.
In the second example, the element will count down from 500 to 0.

Global Configuration

You can globally configure the speed and offset by providing a configuration using CounterService.

{
  provide: CounterService,
  useValue: {
    speed: 40, //by milli sec
    offset: 100, // Offset from viewport to trigger
  },
}

License

MIT License