<grantcodes-stat-counter>

A Lit web component that displays animated stat counters that interpolate between start and end values over time. Perfect for showing metrics, KPIs, and data that changes over time with smooth animations.

This webcomponent follows the open-wc recommendation.

Installation

npm i @grantcodes/stat-counter

Basic Usage

<script type="module">
  import '@grantcodes/stat-counter/stat-counter.js';
</script>

<grantcodes-stat-counter></grantcodes-stat-counter>

Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | startValue | Number | 0 | The starting value for the counter | | endValue | Number | 100 | The ending value for the counter | | startDate | String | '' | Start date in YYYY-MM-DD format | | endDate | String | '' | End date in YYYY-MM-DD format | | exponentialPower | Number | 1 | Power of the exponential curve (1 = linear, >1 = exponential) | | scale | Number | 1 | Scale factor to divide the displayed value by |

Usage Examples

1. Simple Linear Growth

<grantcodes-stat-counter
  start-value="1000"
  end-value="10000"
  start-date="2024-01-01"
  end-date="2024-12-31"
  exponential-power="1">
</grantcodes-stat-counter>

2. Exponential Growth (for exponential data)

<grantcodes-stat-counter
  start-value="10"
  end-value="1000000"
  start-date="2024-01-01"
  end-date="2024-12-31"
  exponential-power="2.5">
</grantcodes-stat-counter>

3. Population Growth Example

<grantcodes-stat-counter
  start-value="8000000000"
  end-value="8500000000"
  start-date="2023-01-01"
  end-date="2025-12-31"
  scaling-mode="linear"
  scale="1000000000">
</grantcodes-stat-counter>
<!-- Shows as 8.0 to 8.5 (billions) -->

4. Real-time Metrics

<!-- Website visitors this month -->
<grantcodes-stat-counter
  start-value="5000"
  end-value="15000"
  start-date="2024-01-01"
  end-date="2024-01-31"
  exponential-power="1">
</grantcodes-stat-counter>

5. Future Projections

<!-- Projected revenue growth -->
<grantcodes-stat-counter
  start-value="100000"
  end-value="500000"
  start-date="2024-06-01"
  end-date="2024-12-31"
  exponential-power="1">
</grantcodes-stat-counter>

6. With Fallback Content

<grantcodes-stat-counter
  start-value="0"
  end-value="100"
  start-date="2024-01-01"
  end-date="2024-12-31">
  5000
</grantcodes-stat-counter>
<!-- Uses 5000 as startValue if no explicit values set -->

How It Works

The component calculates the current value based on:

1. Current time vs. start/end dates
2. Exponential power (configurable curve strength)
3. Animation triggers when the element comes into view
4. Smooth transitions using View Transitions API (with fallback)

Time-based Interpolation

• Before start date: Shows startValue
• Between dates: Interpolates based on elapsed time
• After end date: Extrapolates beyond endValue

Exponential Power

• Linear (power = 1): value = start + (end - start) * progress
• Exponential (power > 1): value = start + (end - start) * progress^power
• Higher power values create stronger exponential curves

Styling

The component uses CSS custom properties for animation timing:

grantcodes-stat-counter {
  --animation-duration: 0.6s;
  --initial-animation-duration: 1.2s;
}

Browser Support

• Modern browsers with ES modules support
• View Transitions API (with graceful fallback)
• Intersection Observer API

Linting and formatting

To scan the project for linting and formatting errors, run

npm run lint

To automatically fix linting and formatting errors, run

npm run format

Testing with Web Test Runner

To execute a single test run:

npm run test

To run the tests in interactive watch mode run:

npm run test:watch

Demoing with Storybook

To run a local instance of Storybook for your component, run

npm run storybook

To build a production version of Storybook, run

npm run storybook:build

Tooling configs

For most of the tools, the configuration is in the package.json to reduce the amount of files in your project.

If you customize the configuration a lot, you can consider moving them to individual files.

Local Demo with web-dev-server

npm start

To run a local development server that serves the basic demo located in demo/index.html