MotionNumber · MotionText

Число, розряди якого крутяться як коліщатка, зокрема розряди, що з’являються й зникають.

ВебReact NativeЧисла й текст

Спробуйте

Підготовка прикладу…

JavaScript вимкнено. Код нижче — повний приклад.

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

Найкоротше використання

Total.jsx

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

Що він бере на себе

Переноси: 999 → 1,000 прокручує кожен змінений розряд в один бік, як одометр.
Розряди, що з’являються чи зникають, в’їжджають і виїжджають у своїй колонці, а не виникають стрибком.
Роздільники, знаки й символи валют з’являються й зникають разом зі своїм розрядом.
Решта розрядів зсувається на нові місця, поки прокручується, тож число ніколи не розвалюється.
Нове значення посеред руху продовжується саме з того, що на екрані.
Форматування ніколи не потребує Intl: передайте текст чи функцію format або ввімкніть intl.

Для чого підходить

Сума кошика, що змінюється, коли додаються товари.
Живий лічильник чи рахунок.
Показник на панелі, що оновлюється кожні кілька секунд.

Props

`MotionNumber`

Проп	Тип	Типово	Опис
`value`	`number \| bigint \| string`	`—`обов’язково	Число чи числовий текст, відформатований вами.
`mode`	`'replace' \| 'roll'`	`'replace'`	`replace` зсуває кожен змінений розряд на один крок; `roll` проходить через проміжні цифри.
`direction`	`'auto' \| 'digit' \| 'up' \| 'down'`	`'auto'`	`auto` йде за зміною величини, щоб переноси крутилися в один бік; `digit` порівнює кожен розряд окремо.
`stagger`	`number`	`45`	Мілісекунди між зміненими розрядами, від одиниць назовні. Уся хвиля обмежена в часі.
`format`	`(value) => string \| Intl.NumberFormatOptions`		Функція, що повертає текст для показу, чи опції `Intl.NumberFormat` (разом з `intl`).
`intl`	`boolean`	`false`	Використовувати вбудований `Intl.NumberFormat`. Типово вимкнено, щоб жодному середовищу виконання не був потрібен `Intl`.
`locale`	`string \| string[]`		Локаль для `intl`.
`prefix`	`string`		Текст перед числом.
`suffix`	`string`		Текст після числа.
`transition`	`Transition`	`spring`	Крива timing `{ duration, easing }` чи пружина `{ tempo: 'spring', spring }`. Після переривання пружини зберігають інерцію.
`onMotionComplete`	`(value) => void`		Виконується зі значенням, коли розряди зупинилися.

`MotionText`

Проп	Тип	Типово	Опис
`children`	`ReactNode`		Текст для показу.
`as`	`element`	`'span'`	Елемент для рендеру.
`transition`	`Transition`	`spring`	Крива timing `{ duration, easing }` чи пружина `{ tempo: 'spring', spring }`. Після переривання пружини зберігають інерцію.
`onMotionComplete`	`(text) => void`		Виконується, коли рух зупиняється.

Решта props передається відрендереному елементу, тож className, style і обробники подій працюють як завжди.

Веб і React Native

У вебі кожен розряд — невеликий стос гліфів, який відтворює Web Animations API, а текст лишається виділюваним. MotionText анімує будь-який текст: числовий прокручується розрядами, решта змінюється.

У React Native число лишається справжнім Text для розкладки, виділення й доступності, зокрема переносів і numberOfLines; гліфи рухаються на нативному драйвері.