MotionNumber · MotionText

A number whose places roll like wheels, including places that appear or disappear.

WebReact NativeNumbers and text

Try it

Preparing the example…

JavaScript is off. The code below is the complete example.

App.jsx

import { useState } from 'react';
import { MotionNumber, MotionText, motionTokens } from '@kkwaenggwari/animated-chorus';
import './styles.css';

const formats = {
  plain: {},
  currency: { intl: true, locale: 'en-US', format: { style: 'currency', currency: 'USD' } },
  // Basis points: every preset and every ±1 step shows a different percentage.
  percent: { format: (value) => `${(value / 100).toFixed(2)}%` },
};

const presets = [9, 10, 999, 1000, 12480, 98765];

export default function App({
  mode = 'roll',
  direction = 'auto',
  format = 'currency',
  stagger = 40,
  spring = 'default',
}) {
  const [value, setValue] = useState(1000);
  const [trend, setTrend] = useState('Ready');

  const change = (next) => {
    setTrend(next > value ? 'Rising' : next < value ? 'Falling' : 'Same value');
    setValue(next);
  };

  return (
    <div className="lab">
      <MotionNumber
        className="value"
        value={value}
        mode={mode}
        direction={direction}
        stagger={stagger}
        transition={motionTokens.spring[spring]}
        {...formats[format]}
      />
      <MotionText className="trend">{trend}</MotionText>
      <div className="presets">
        {presets.map((preset) => (
          <button key={preset} onClick={() => change(preset)}>
            {preset}
          </button>
        ))}
      </div>
      <div className="steps">
        <button onClick={() => change(value - 1)}>−1</button>
        <button onClick={() => change(value + 1)}>+1</button>
        <button onClick={() => change(value * 10)}>×10</button>
        <button onClick={() => change(Math.round(value / 10))}>÷10</button>
      </div>
    </div>
  );
}

styles.css

.lab {
  display: grid;
  justify-items: center;
  gap: 14px;
  padding: 32px 20px 28px;
}

.value {
  font:
    800 clamp(44px, 11vw, 80px)/1.05 system-ui,
    sans-serif;
  font-variant-numeric: tabular-nums;
  letter-spacing: -0.03em;
  color: #0e2e24;
}

.trend {
  padding: 4px 12px;
  border-radius: 999px;
  background: #eaf6f0;
  color: #176b52;
  font-weight: 650;
  font-size: 14px;
}

.presets,
.steps {
  display: flex;
  flex-wrap: wrap;
  justify-content: center;
  gap: 8px;
}

.presets button,
.steps button {
  min-width: 56px;
  min-height: 44px;
  padding: 0 14px;
  border: 1px solid #cfe8dc;
  border-radius: 999px;
  background: #fff;
  font:
    600 15px system-ui,
    sans-serif;
  font-variant-numeric: tabular-nums;
  color: #0e2e24;
  cursor: pointer;
}

.steps button {
  background: #f4faf7;
}

.presets button:hover,
.steps button:hover {
  border-color: #176b52;
}

Shortest usage

Total.jsx

<MotionNumber value={count} />
<MotionNumber value={total} mode="roll" intl locale="en-US"
  format={{ style: 'currency', currency: 'USD' }} />
<MotionText>{status}</MotionText>

What it handles for you

Carries: 999 → 1,000 rolls every changed place the same way, like an odometer.
Places that appear or disappear roll in or out of their own column instead of popping.
Separators, signs and currency symbols fade in and out with the place they belong to.
Remaining places slide to their new positions while they roll, so the number never splits.
A new value in the middle of a motion continues from exactly what is on screen.
Formatting never requires Intl: pass text or a format function, or opt in with intl.

Use it for

A cart total that changes as items are added.
A live counter or score.
A dashboard figure that refreshes every few seconds.

Props

`MotionNumber`

Prop	Type	Default	Description
`value`	`number \| bigint \| string`	`—`required	The number, or caller-formatted numeric text.
`mode`	`'replace' \| 'roll'`	`'replace'`	`replace` moves each changed place one step; `roll` passes through the digits in between.
`direction`	`'auto' \| 'digit' \| 'up' \| 'down'`	`'auto'`	`auto` follows the change in size so carries roll one way; `digit` compares each place on its own.
`stagger`	`number`	`45`	Milliseconds between changed places, from the units outward. The whole ripple is bounded.
`format`	`(value) => string \| Intl.NumberFormatOptions`		A function that returns the text to show, or `Intl.NumberFormat` options (with `intl`).
`intl`	`boolean`	`false`	Use the built-in `Intl.NumberFormat`. Off by default so no runtime needs `Intl`.
`locale`	`string \| string[]`		Locale for `intl`.
`prefix`	`string`		Text before the number.
`suffix`	`string`		Text after the number.
`transition`	`Transition`	`spring`	A timing curve `{ duration, easing }` or a spring `{ tempo: 'spring', spring }`. Springs keep their momentum when interrupted.
`onMotionComplete`	`(value) => void`		Runs with the value once the places have settled.

`MotionText`

Prop	Type	Default	Description
`children`	`ReactNode`		The text to show.
`as`	`element`	`'span'`	The element to render.
`transition`	`Transition`	`spring`	A timing curve `{ duration, easing }` or a spring `{ tempo: 'spring', spring }`. Springs keep their momentum when interrupted.
`onMotionComplete`	`(text) => void`		Runs when the motion settles.

Other props go to the rendered element, so className, style and event handlers work as usual.

Web and React Native

On the web each place is a small stack of glyphs played by the Web Animations API, and the text stays selectable. MotionText animates any text: numeric text rolls per place, other text swaps.

On React Native the number stays a real Text for layout, selection and accessibility, including wrapping and numberOfLines; the glyphs move on the native driver.