NumberFlow: анимация чисел, 24 примера и готовый код

Цена изменилась, счётчик перескочил на новый разряд, процент вырос. Можно просто заменить текст, а можно сделать изменение заметным и при этом не превращать интерфейс в аттракцион. В этой статье собрана мастерская: выбирайте пример, меняйте числа и проверяйте, подходит ли такое движение вашему проекту.

Библиотека по ссылке называется NumberFlow, её автор — Maxwell Barvian; это компонент для анимированных чисел, а не MotionNumber, как иногда пишут в подборках: название и автор указаны в официальной документации. На этой странице используется настоящий JavaScript-компонент NumberFlow 0.6.2, собранный вместе с мастерской и размещённый на нашем сервере.

Что можно попробовать прямо здесь

В каталоге 24 готовых перехода: смена разрядов, валюты, проценты, дроби, единицы измерения и интерфейсные подписи. Ниже находятся шесть практических сценариев и отдельный таймер с минутами и секундами.

• Разряды: 9 → 10, 99 → 100, переход к тысяче и миллиону, отрицательные значения.
• Форматы: рубли, доллары, евро, проценты, короткая запись и дробные числа.
• Единицы: температура, расстояние, объём, масса, размер файла и скорость.
• Интерфейс: позиция в списке, изменение со знаком, ведущие нули, цена за месяц и очки.

Мастерская: 24 числовых перехода

Начните с 99 → 100: здесь хорошо видно появление нового разряда. Затем откройте цену в рублях, поменяйте точность и сравните короткое движение со спокойным переходом на 1,6 секунды.

В числовых полях можно использовать запятую или точку и пробелы между разрядами. Диапазон этой мастерской ограничен числами от −1 000 000 000 до 1 000 000 000; формулы, экспоненциальная запись и нечисловые значения не принимаются.

Какие настройки стоит сравнить

В NumberFlow форматирование задаётся через Intl.NumberFormat, а направление, продолжительность и прозрачность переходов настраиваются отдельно: свойства описаны в JavaScript-документации. В мастерской основные параметры вынесены в обычные поля, чтобы сравнивать их без редактирования кода.

• Локаль и формат: определяют разделители, знак валюты и вид единиц; попробуйте одну цену в ru-RU и en-US, используя параметры из документации format и locales.
• Направление: trend: 1 направляет цифры вверх, -1 вниз, а 0 позволяет каждому разряду выбирать направление самостоятельно; по умолчанию используется знак изменения общего числа, согласно описанию trend.
• Длительность: transformTiming управляет перестроением, spinTiming вращением цифр, opacityTiming появлением и исчезновением символов; назначения перечислены в разделе Timings.
• Continuous: официальный плагин создаёт впечатление прохождения через промежуточные значения, но не действует при trend: 0, как уточняет документация плагина.

Для эксперимента с процентами выберите соответствующий пресет и сравните исходные 0,25 и конечные 0,86. Здесь вводится доля, поэтому получаются 25% и 86%, а не 0,25% и 0,86%; в блоке кода видны точные исходные значения и настройки.

Необязательно делать все переходы одинаковыми. Попробуйте короткую анимацию для корзины и более плавную для отдельного крупного показателя, затем оцените, остаётся ли изменение понятным без дополнительных пояснений.

Практика: цены, показатели и прогресс

Эти стенды показывают не разные декоративные оболочки одного счётчика, а разные способы обновления данных. Поменяйте количество в корзине, переключите период тарифа, пройдите три набора показателей и проверьте паузу прогресса.

Для совместного изменения нескольких компонентов используется оригинальный number-flow-group: он синхронизирует переходы всех вложенных чисел, включая непрямых потомков, и требует отдельного импорта, согласно разделу Grouping. Сами расчёты и переключатели написаны для этой страницы; библиотека отвечает за отображение и движение чисел.

Таймер: почему секунды требуют настройки

У обычного десятичного разряда десять цифр, но у десятков секунд допустимы только 0–5. NumberFlow позволяет задать максимальную цифру через digits; это свойство не реактивно, поэтому его устанавливают до первого обновления компонента, как указано в документации digits.

Нажмите «Минус секунда» при 01:00 и посмотрите переход к 00:59. Затем установите 3 секунды и запустите отсчёт до нуля; демонстрация останавливается при уходе с вкладки и не предназначена для точного измерения времени.

Подключение на JavaScript, React, Vue и Svelte

Для JavaScript используется пакет number-flow, для React, Vue и Svelte существуют отдельные пакеты и компоненты: смотрите JavaScript, React, Vue и Svelte. Ниже приведены минимальные варианты с кнопкой; в мастерской выше код формируется из выбранных вами параметров.

JavaScript без фреймворка

Установите npm install number-flow в проект со сборщиком, добавьте разметку и импортируйте модуль. Первый update() устанавливает число, следующие вызовы анимируют изменение, согласно Basic usage.

<number-flow id="price"></number-flow>
<button id="change">Изменить цену</button>
<script type="module">
  import 'number-flow';
  const flow = document.querySelector('#price');
  flow.locales = 'ru-RU';
  flow.format = {
    style: 'currency', currency: 'RUB',
    maximumFractionDigits: 0
  };
  flow.numberSuffix = '/мес.';
  flow.respectMotionPreference = true;
  flow.update(390);
  document.querySelector('#change').onclick = () => flow.update(590);
</script>

Без сборщика официальный пример допускает импорт с https://esm.sh/number-flow, что показано в документации JavaScript. Наша кнопка «Скачать HTML» использует зафиксированный импорт https://esm.sh/number-flow@0.6.2, поэтому скачанному файлу нужен интернет; встроенные стенды этой статьи, напротив, получают библиотеку с нашего сервера.

React

Установите npm install @number-flow/react и передавайте число через value; изменение этого свойства запускает переход, согласно документации React. В среде с серверными компонентами этот интерактивный пример должен находиться на клиентской стороне.

'use client';
import { useState } from 'react';
import NumberFlow from '@number-flow/react';

export default function Counter() {
  const [value, setValue] = useState(99);
  return (
    <div>
      <NumberFlow value={value} locales="ru-RU" />
      <button onClick={() => setValue(v => v + 1)}>
        Прибавить 1
      </button>
    </div>
  );
}

Vue

Для Vue установите npm install @number-flow/vue и свяжите value с реактивным значением, следуя официальному примеру. Кнопка ниже меняет только число, а компонент отвечает за переход.

<script setup>
import { ref } from 'vue';
import NumberFlow from '@number-flow/vue';
const value = ref(99);
</script>
<template>
  <NumberFlow :value="value" locales="ru-RU" />
  <button @click="value += 1">Прибавить 1</button>
</template>

Svelte

Пакет @number-flow/svelte также принимает свойство value, как показано в документации Svelte. Этот пример записан для Svelte 5 с реактивным состоянием $state.

<script>
  import NumberFlow from '@number-flow/svelte';
  let value = $state(99);
</script>
<NumberFlow {value} locales="ru-RU" />
<button onclick={() => value += 1}>Прибавить 1</button>

Ограничения, доступность и лицензия

• Не любой вид записи: научная и инженерная нотация, нелатинские цифры и RTL-локали пока не поддерживаются; ограничения прямо перечислены в документации.
• Уменьшение движения: respectMotionPreference включён по умолчанию, а animated: false отключает и завершает анимации, согласно описанию свойств.
• Возможности браузера: библиотека предоставляет canAnimate для проверки необходимых функций, как указано в Utilities; мастерская показывает текущий режим над примерами.
• Оформление: фон и границы непосредственно на number-flow не масштабируются плавно во время перехода, по предупреждению в Limitations; в наших стендах оформление вынесено на внешний контейнер.
• Лицензия MIT: разрешает использование и изменение при сохранении уведомления об авторских правах и текста лицензии, включая существенные части копий; условия опубликованы в LICENSE.md.

В сборке мастерской сохранены уведомления о лицензиях NumberFlow и его зависимости. Уважение настройки уменьшенного движения здесь не отключается даже при включённом флажке анимации, а для показателей и таймера доступны текстовые состояния.

Когда стоит использовать NumberFlow

Я бы начинал с одного значимого числа: суммы заказа, выбранного тарифа или прогресса действия. Если после нескольких переключений переход помогает увидеть изменение, его можно оставить; если он отвлекает или заставляет ждать, уменьшите длительность либо замените анимацию обычным обновлением текста.

Перед внедрением проверьте большие и отрицательные значения, округление, появление нового разряда, узкий экран и режим уменьшенного движения. Начните с мастерской выше, а затем повторите те же состояния на своих реальных данных и в своём интерфейсе.

Продолжить изучение можно в официальной галерее и репозитории NumberFlow. На нашем сайте для других задач есть мастерская CSS-анимаций Animista и интерактивные компоненты Kokonut UI.