react-native-number-flow

A per-digit animated number ticker for React Native - only the digits that change move, and they roll up when the value increases, down when it decreases. Pure TypeScript, built on the Animated API, with no native modules to link.

Features

• Per-digit roll: only the characters that actually changed move.
• Direction-aware: digits roll up on increase, down on decrease.
• Locale-free thousands grouping and fixed decimal places out of the box.
• Bring-your-own format for currency, percentages, units, prefixes or suffixes.
• Configurable duration and easing; standard text style and color.
• Pure TypeScript, no native modules, no Reanimated. translateY runs on the native driver.
• Right-aligned slots: a growing number inserts a new leading character instead of re-rolling the existing leading digit.

Installation

npm install react-native-number-flow

This library has no runtime dependencies beyond its peers:

npm install react react-native

Usage

import { NumberFlow, thousandsLong } from 'react-native-number-flow';

<NumberFlow value={score} format={thousandsLong()} />;

Every value change animates only the digits that actually changed.

Price with two decimal places

import { NumberFlow, thousands } from 'react-native-number-flow';

<NumberFlow
  value={price}
  format={thousands({ decimalPlaces: 2 })}
  textStyle={{ fontSize: 34, fontWeight: '600' }}
/>;

Custom format

<NumberFlow value={balance} format={(v) => `$${thousands({ decimalPlaces: 2 })(v)}`} />

Custom animation

import { Easing } from 'react-native';

<NumberFlow value={score} duration={600} easing={Easing.out(Easing.cubic)} />

Steady columns with tabular figures

Each character sizes itself to the digit it shows. With a proportional font a 1 is narrower than an 8, so the row can shift sideways as digits change. Add fontVariant: ['tabular-nums'] to the text style to give every figure the same width, which keeps the columns from moving while they roll:

<NumberFlow value={score} textStyle={{ fontSize: 48, fontVariant: ['tabular-nums'] }} />

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | value | number | required | The numeric value to display. | | format | (value: number) => string | plainDouble | Turns the value into the displayed string. | | textStyle | StyleProp<TextStyle> | - | Style applied to every character. | | color | string | - | Overrides the text color. | | duration | number | 450 | Roll duration in milliseconds. | | easing | EasingFunction | Easing.inOut(Easing.ease) | Roll easing. |

Formatting helpers

thousands(options), thousandsLong(grouping), plainDouble, plainLong, and the pure formatWithThousands(value, options) / groupThousands(digits, grouping) are all exported, so you can reuse them without the component.

A note on growing numbers

Slots are keyed by their distance from the right edge of the string. When a number grows (for example 99 to 100), the existing trailing digits stay put and a fresh leading character rolls in on the left, rather than the leading digit visibly changing. This differs intentionally from a strict left-index ticker.

Other platforms

The same number ticker is available for other platforms:

• Compose Multiplatform (original): number-flow
• Flutter: animated_number_flow

License

Licensed under the Apache License, Version 2.0. See LICENSE.