Alpine CountUp Plugin

A lightweight Alpine.js directive plugin that animates numbers counting up when they come into view, using IntersectionObserver.
It supports customizable start and end values, duration, easing, prefixes, suffixes, decimals, and tolerance for early triggering.

Features

• Counts from 0 to a target number or from a custom start to end
• Starts only when the element enters the viewport
• Supports easing for smooth animations
• Prefix and suffix support (for currency, percentages, etc.)
• Decimals for fractional values
• Tolerance for early start before the element fully appears

Installation

npm install @designbycode/apline-countup

Include Alpine.js and the CountUp plugin:

import Alpine from 'alpinejs'
import AlpineCountUp from '@designbycode/alpine-countup.js'

Alpine.plugin(AlpineCountUp)
Alpine.start()

Or via a <script> tag (with ES modules):

<script type="module">
    import Alpine from 'https://unpkg.com/[email protected]/dist/module.esm.js'
    import AlpineCountUp from '@designbycode/alpine-countup.js'

    Alpine.plugin(AlpineCountUp)
    Alpine.start()
</script>

Usage

Basic Example

<div x-data>
    <span x-countup="{ end: 1000 }"></span>
</div>

Starts counting from 0 to 1000 when in view.

Start and End Values

<div x-data>
    <span x-countup="{ start: 500, end: 1500, duration: 3000 }"></span>
</div>

Counts from 500 to 1500 over 3 seconds.

With Prefix and Suffix

<div x-data>
    <span x-countup="{ end: 200, prefix: '$' }"></span>
    <br>
    <span x-countup="{ end: 99, suffix: '%' }"></span>
</div>

• $200
• 99%

With Decimals

<div x-data>
    <span x-countup="{ end: 3.14159, decimals: 3 }"></span>
</div>

Displays: 3.142

With Tolerance

<div x-data>
    <span x-countup="{ end: 1000, tolerance: 100 }"></span>
</div>

Starts counting 100px before the element fully enters the viewport.

Combined Example

<div x-data>
    <span x-countup="{ 
        start: 50, 
        end: 500, 
        duration: 2500, 
        prefix: '$', 
        suffix: ' USD', 
        decimals: 2, 
        tolerance: 150 
    }"></span>
</div>

Counts from $50.00 to $500.00 USD over 2.5 seconds, starting 150px early.

Options

| Option | Type | Default | Description | | ----------- | ------ | ------- | -------------------------------------------------- | | start | number | 0 | Starting value of the counter | | end | number | 0 | Target value of the counter | | duration | number | 2000 | Duration in milliseconds | | decimals | number | 0 | Number of decimal places | | prefix | string | "" | Text to display before the number | | suffix | string | "" | Text to display after the number | | tolerance | number | 0 | Pixel offset to trigger early (positive = earlier) |

How it Works

• Uses IntersectionObserver to detect when the element comes into view
• Supports rootMargin to allow tolerance-based early triggering
• Animates with requestAnimationFrame for smooth transitions
• Use an ease-out cubic function to slow down at the end

License

MIT License