@arraypress/count-up

React hook for animating numbers from 0 to a target value with easing. Handles suffixes (e.g., "10,000+"), decimal places, and comma formatting.

Install

npm install @arraypress/count-up

Peer dependency: react >= 18

Usage

useCountUp(value, isActive, duration?)

Animates a number from 0 to the target when isActive becomes true. Parses strings like "10,000+", "4.9/5", "50,000+" — extracts the number, animates it with a cubic ease-out curve, then reattaches the suffix.

import { useCountUp } from '@arraypress/count-up';

function StatCard({ value, label }) {
  const [ref, inView] = useInView(0.1); // from @arraypress/in-view
  const display = useCountUp(value, inView);

  return (
    <div ref={ref}>
      <span>{display}</span>
      <span>{label}</span>
    </div>
  );
}

// Usage:
<StatCard value="10,000+" label="Downloads" />
<StatCard value="4.9/5" label="Rating" />
<StatCard value="99.9%" label="Uptime" />

Parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | value | string \| number | — | Target value. Can include commas, decimals, and suffixes. | | isActive | boolean | — | Whether the animation should start. | | duration | number | 1500 | Animation duration in milliseconds. |

Returns: The current display value (animated string or the original value).

parseValue(str)

Parse a value string into its numeric component and suffix.

import { parseValue } from '@arraypress/count-up';

parseValue('10,000+');  // { target: 10000, suffix: '+', hasCommas: true, decimals: 0, ... }
parseValue('4.9/5');    // { target: 4.9, suffix: '/5', hasDecimal: true, decimals: 1, ... }

formatNumber(value, decimals, useCommas)

Format a number with optional comma separators and decimal places.

import { formatNumber } from '@arraypress/count-up';

formatNumber(10000, 0, true);    // '10,000'
formatNumber(4.912, 1, false);   // '4.9'
formatNumber(1234.5, 1, true);   // '1,234.5'

easeOutCubic(t)

Cubic ease-out function. Takes a progress value (0-1), returns eased value (0-1).

import { easeOutCubic } from '@arraypress/count-up';

easeOutCubic(0);   // 0
easeOutCubic(0.5); // 0.875
easeOutCubic(1);   // 1

License

MIT