MotionNumber · MotionText

Eine Zahl, deren Stellen wie Räder rollen – auch Stellen, die hinzukommen oder wegfallen.

WebReact NativeZahlen und Text

Ausprobieren

Beispiel wird vorbereitet…

JavaScript ist aus. Der Code unten ist das vollständige Beispiel.

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;
}

Kürzeste Nutzung

Total.jsx

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

Was sie dir abnimmt

Überträge: 999 → 1,000 lässt jede geänderte Stelle in dieselbe Richtung rollen, wie bei einem Kilometerzähler.
Stellen, die hinzukommen oder wegfallen, rollen in ihrer eigenen Spalte herein und hinaus, statt aufzuploppen.
Trennzeichen, Vorzeichen und Währungssymbole blenden mit der Stelle ein und aus, zu der sie gehören.
Verbleibende Stellen gleiten an ihre neue Position, während sie rollen – die Zahl bricht nie auseinander.
Ein neuer Wert mitten in der Bewegung setzt genau dort an, was auf dem Bildschirm ist.
Formatierung braucht nie Intl: Übergib Text oder eine format-Funktion, oder aktiviere es mit intl.

Gut für

Eine Warenkorbsumme, die sich beim Hinzufügen von Artikeln ändert.
Ein Live-Zähler oder Spielstand.
Eine Dashboard-Zahl, die sich alle paar Sekunden aktualisiert.

props

`MotionNumber`

Prop	Typ	Standard	Beschreibung
`value`	`number \| bigint \| string`	`—`erforderlich	Die Zahl oder vom Aufrufer formatierter Zahlentext.
`mode`	`'replace' \| 'roll'`	`'replace'`	`replace` bewegt jede geänderte Stelle um einen Schritt; `roll` läuft durch die Ziffern dazwischen.
`direction`	`'auto' \| 'digit' \| 'up' \| 'down'`	`'auto'`	`auto` folgt der Größenänderung, sodass Überträge in eine Richtung rollen; `digit` vergleicht jede Stelle für sich.
`stagger`	`number`	`45`	Millisekunden zwischen geänderten Stellen, von den Einern nach außen. Die gesamte Welle ist begrenzt.
`format`	`(value) => string \| Intl.NumberFormatOptions`		Eine Funktion, die den anzuzeigenden Text zurückgibt, oder `Intl.NumberFormat`-Optionen (mit `intl`).
`intl`	`boolean`	`false`	Nutzt das eingebaute `Intl.NumberFormat`. Standardmäßig aus, damit keine Laufzeitumgebung `Intl` braucht.
`locale`	`string \| string[]`		Locale für `intl`.
`prefix`	`string`		Text vor der Zahl.
`suffix`	`string`		Text nach der Zahl.
`transition`	`Transition`	`spring`	Eine Timing-Kurve `{ duration, easing }` oder eine Feder `{ tempo: 'spring', spring }`. Federn behalten bei Unterbrechung ihren Schwung.
`onMotionComplete`	`(value) => void`		Läuft mit dem Wert, sobald die Stellen zur Ruhe gekommen sind.

`MotionText`

Prop	Typ	Standard	Beschreibung
`children`	`ReactNode`		Der anzuzeigende Text.
`as`	`element`	`'span'`	Das zu rendernde Element.
`transition`	`Transition`	`spring`	Eine Timing-Kurve `{ duration, easing }` oder eine Feder `{ tempo: 'spring', spring }`. Federn behalten bei Unterbrechung ihren Schwung.
`onMotionComplete`	`(text) => void`		Läuft, wenn die Bewegung zur Ruhe kommt.

Weitere props gehen an das gerenderte Element, also funktionieren className, style und Event-Handler wie gewohnt.

Web und React Native

Im Web ist jede Stelle ein kleiner Glyphen-Stapel, den die Web Animations API abspielt, und der Text bleibt markierbar. MotionText animiert beliebigen Text: Zahlentext rollt pro Stelle, anderer Text wird ausgetauscht.

Unter React Native bleibt die Zahl ein echtes Text für Layout, Auswahl und Barrierefreiheit, inklusive Umbruch und numberOfLines; die Glyphen bewegen sich mit dem nativen Treiber.