Overview [#overview] Number animation is the sort of effect that makes your product feel great, making it ideal for high quality financial apps, dashboards, and other applications where dynamically changing numbers are displayed. This library wants to be easy to use, and at the same time be able to handle anything you throw at it - from simple number transitions to complex price tickers, step counters, and more. It's also built to support both View-based and Skia-based rendering backends, as Skia is often used for graphs and charts that require synchronized number animations. Attribution [#attribution] This library is a React Native reimplementation inspired by [NumberFlow](https://number-flow.barvian.me/) by [Maxwell Barvian](https://github.com/barvian). The animation patterns, easing curves, and digit-rolling approach are adapted from the original web implementation. All code in this library is original. # Quick Start Import NumberFlow [#import-numberflow] ```tsx import { NumberFlow } from 'number-flow-react-native'; ``` Use it with a value [#use-it-with-a-value] ```tsx function PriceDisplay() { const [price, setPrice] = useState(42.99); return ( ); } ``` Every time `price` changes, each digit rolls smoothly to its new value. Explore the components [#explore-the-components] Check out the [Components](/docs/components) section for all four components (`NumberFlow`, `TimeFlow`, `SkiaNumberFlow`, and `SkiaTimeFlow`) with full prop references. Import Paths [#import-paths] The library exposes three entry points: ```tsx // Native components (default) import { NumberFlow, TimeFlow } from 'number-flow-react-native'; // Explicit native-only import (same as default) import { NumberFlow, TimeFlow } from 'number-flow-react-native/native'; // Skia components (requires @shopify/react-native-skia) import { SkiaNumberFlow, SkiaTimeFlow, useSkiaFont } from 'number-flow-react-native/skia'; ``` The root import only includes native components. It does **not** pull in `@shopify/react-native-skia`. You only need Skia installed if you import from `number-flow-react-native/skia`. # NumberFlow `NumberFlow` is the View-based animated number component. It renders using React Native Animated Views with Reanimated SharedValues, with no extra dependencies beyond `react-native-reanimated`. Each digit position contains a virtual wheel of digits 0–9, and transitions are achieved by translating the wheel's Y position. Import [#import] ```tsx import { NumberFlow } from 'number-flow-react-native'; ``` Basic Usage [#basic-usage] Every time `price` changes, each digit rolls independently to its new value. Props [#props] Value props [#value-props] | Prop | Type | Default | Description | | --------- | -------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `value` | `number` | **(required)** | Numeric value to display. | | `format` | `Intl.NumberFormatOptions` | `undefined` | Options passed to `Intl.NumberFormat`: currencies, percentages, compact notation, scientific, units, etc. | | `locales` | `Intl.LocalesArgument` | `undefined` | Locale(s) for `Intl.NumberFormat`. Controls grouping separators, decimal marks, currency symbol placement, and numeral system. | Style props [#style-props] | Prop | Type | Default | Description | | ---------------- | --------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `style` | `TextStyle` | `undefined` | Text styling. `fontSize` defaults to `16` when omitted; `fontFamily` defaults to the platform system font. `textAlign` defaults to `"left"`. Accepts any `TextStyle` property. | | `prefix` | `string` | `""` | Static string prepended before the number. Animates in/out when added or removed. | | `suffix` | `string` | `""` | Static string appended after the number. Animates in/out when added or removed. | | `digits` | `Record` | `undefined` | Per-position digit constraints. Position `0` = ones, `1` = tens, `2` = hundreds, etc. Each entry defines `{ max: N }` (1–9) as the highest value for that digit wheel. | | `containerStyle` | `ViewStyle` | `undefined` | Style applied to the outer container `View`. | Animation behavior props [#animation-behavior-props] | Prop | Type | Default | Description | | ------------------------- | -------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `trend` | `Trend \| ((prev: number, next: number) => Trend)` | auto | Digit spin direction. `1` = always up, `-1` = always down, `0` = shortest path per digit. Or a function receiving `(prev, next)` returning the direction. Auto-detects from value changes when omitted. | | `animated` | `boolean` | `true` | Set to `false` to disable all animations and update instantly. | | `respectMotionPreference` | `boolean` | `true` | Disables animations when the device "Reduce Motion" setting is on. | | `continuous` | `boolean` | `false` | When `true`, unchanged lower-significance digits spin through a full cycle during transitions, making the number appear to pass through intermediate values. | | `mask` | `boolean` | `true` | Enable edge gradient fade on digit slots. When `@rednegniw/masked-view` (or, in Expo projects, `@expo/ui` 56.0.3+) is installed, uses a MaskedView for smooth spatial gradient masking. Otherwise falls back to per-digit opacity fading. Set to `false` to disable masking entirely. | | `transformTiming` | `TimingConfig` | 900ms deceleration | Timing for layout transforms (position, width changes). Uses NumberFlow's signature deceleration curve. | | `spinTiming` | `TimingConfig` | Falls back to `transformTiming` | Timing for digit spin/rolling. | | `opacityTiming` | `TimingConfig` | 450ms ease-out | Timing for enter/exit opacity transitions. | | `onAnimationsStart` | `() => void` | `undefined` | Called when update animations begin. | | `onAnimationsFinish` | `() => void` | `undefined` | Called when all update animations complete. | Type references [#type-references] ```tsx type TimingConfig = { duration: number; easing: EasingFunction; // (t: 0→1) => 0→1 }; type Trend = -1 | 0 | 1; type TrendProp = Trend | ((prev: number, next: number) => Trend); ``` Accessibility [#accessibility] `NumberFlow` automatically sets `accessibilityRole="text"` and an `accessibilityLabel` with the full formatted value. Screen readers announce the complete number (e.g. "$42.99") rather than individual digit changes. # SkiaNumberFlow `SkiaNumberFlow` is the Canvas-based animated number component. It renders using `@shopify/react-native-skia` and supports worklet-driven scrubbing via `SharedValue` for zero-latency UI thread updates. Ideal for charts, sliders, gesture-driven UIs, and scenarios with many simultaneous animated numbers. Import [#import] ```tsx import { SkiaNumberFlow, useSkiaFont } from 'number-flow-react-native/skia'; ``` `SkiaNumberFlow` must be rendered inside a Skia `Canvas` component. It renders Skia primitives (`Group`, `Text`), not React Native Views. Basic Usage [#basic-usage] Use the [`useSkiaFont`](/docs/hooks/use-skia-font) hook for a guaranteed non-null font. It provides a synchronous system-font fallback via `matchFont`, so the component renders immediately instead of showing blank until the custom font loads. Props [#props] Value props (mutually exclusive) [#value-props-mutually-exclusive] Provide either `value` (JS-driven) or `sharedValue` (worklet-driven), not both. | Prop | Type | Default | Description | | ------------- | -------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `value` | `number` | `undefined` | JS-thread numeric value. Triggers animated transitions on change. Mutually exclusive with `sharedValue`. | | `format` | `Intl.NumberFormatOptions` | `undefined` | Options passed to `Intl.NumberFormat`. Only available with `value`. | | `locales` | `Intl.LocalesArgument` | `undefined` | Locale(s) for `Intl.NumberFormat`. Only available with `value`. | | `sharedValue` | `SharedValue` | `undefined` | Worklet-driven pre-formatted string (e.g. `"$42.99"`). Updates on the UI thread with no JS bridge crossing. Mutually exclusive with `value`. | Rendering props [#rendering-props] | Prop | Type | Default | Description | | --------------------------- | --------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `font` | `SkFont \| null` | **(required)** | Skia font instance from `useFont()` or `useSkiaFont()`. Renders empty until font loads. | | `color` | `string \| SharedValue` | `"#000000"` | Text color. Accepts a static string or a `SharedValue` for animated color transitions. | | `x` | `number` | `0` | X position within the Canvas. | | `y` | `number` | `0` | Y position within the Canvas (baseline of the text). | | `width` | `number` | `0` | Available width for alignment calculations. | | `textAlign` | `"left" \| "right" \| "center"` | `"left"` | Text alignment within the available width. | | `prefix` | `string` | `""` | Static string prepended before the number. | | `suffix` | `string` | `""` | Static string appended after the number. | | `opacity` | `SharedValue` | `undefined` | Parent opacity for animation coordination. | | `digits` | `Record` | `undefined` | Per-position digit constraints. Position `0` = ones, `1` = tens, etc. | | `tabularNums` | `boolean` | `false` | Force equal-width digits by interpolating between min and max digit glyph widths. Equivalent to `fontVariant: ['tabular-nums']` on native components. | | `scrubDigitWidthPercentile` | `number` (0–1) | `0.75` | Controls digit width during worklet-driven scrubbing. `0` = narrowest, `0.5` = average, `1` = widest (no clipping). Only affects digits; symbols keep natural width. | Animation behavior props [#animation-behavior-props] All props from `AnimationBehaviorProps` are supported: `trend`, `animated`, `respectMotionPreference`, `continuous`, `mask`, `transformTiming`, `spinTiming`, `opacityTiming`, `onAnimationsStart`, `onAnimationsFinish`. See [NumberFlow](/docs/components/number-flow#animation-behavior-props) for details. Worklet Scrubbing [#worklet-scrubbing] When using `sharedValue`, the component updates on the UI thread with zero JS bridge overhead. This is ideal for gesture-driven scenarios. It is also the right mode for high-frequency updates across many components: each `value` prop change costs a React commit plus a synchronous canvas re-record on the JS thread, which falls behind when many components tick quickly, while `sharedValue` updates produce no React commits at all. See [Performance Tips](/docs/guides/performance-tips#choosing-a-renderer-and-update-mode) for how to choose. ```tsx import { View } from 'react-native'; import { Canvas } from '@shopify/react-native-skia'; import { useSharedValue, useDerivedValue } from 'react-native-reanimated'; import { Gesture, GestureDetector } from 'react-native-gesture-handler'; import { SkiaNumberFlow, useSkiaFont } from 'number-flow-react-native/skia'; function ScrubSlider() { const font = useSkiaFont('https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuI6fMZg.ttf', 32); const progress = useSharedValue(0); const formattedValue = useDerivedValue(() => { return `$${(progress.value * 1000).toFixed(2)}`; }); const pan = Gesture.Pan().onUpdate((e) => { progress.value = Math.max(0, Math.min(1, e.translationX / 300)); }); return (

); } ``` The `scrubDigitWidthPercentile` prop controls width allocation during scrubbing. The default `0.75` (75th percentile between narrowest and widest digit) balances tightness with avoiding clipping. Lower values produce tighter spacing but may clip wide digits like "0"; higher values add more spacing. Accessibility [#accessibility] Value changes are auto-announced for screen reader users via `AccessibilityInfo.announceForAccessibility`. For VoiceOver/TalkBack focus-based reading, set `accessibilityLabel` on the parent `Canvas`: ```tsx import { useFormattedValue } from 'number-flow-react-native'; const label = useFormattedValue(value, format);

``` # SkiaTimeFlow `SkiaTimeFlow` is the Canvas-based animated time display. Like `TimeFlow`, it supports hours/minutes/seconds segments, 12h/24h formats, and timestamp input, but renders in Skia and supports worklet-driven scrubbing via `SharedValue`. Import [#import] ```tsx import { SkiaTimeFlow, useSkiaFont } from 'number-flow-react-native/skia'; ``` Basic Usage [#basic-usage] Props [#props] Time value props (mutually exclusive with sharedValue) [#time-value-props-mutually-exclusive-with-sharedvalue] | Prop | Type | Default | Description | | ---------------- | --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------- | | `hours` | `number` (0–23) | `undefined` | Hours value. Omit to hide the hours segment. | | `minutes` | `number` (0–59) | **(required)** | Minutes value. Required when using direct time values. | | `seconds` | `number` (0–59) | `undefined` | Seconds value. Omit to hide the seconds segment. | | `centiseconds` | `number` (0–99) | `undefined` | Centiseconds value. Omit to hide. Requires `seconds` to be set. Displayed as ".CC" after seconds. | | `timestamp` | `number` | `undefined` | Unix timestamp in milliseconds. Auto-extracts hours/minutes/seconds. | | `timezoneOffset` | `number` | `undefined` | Timezone offset in milliseconds for timestamp mode. | | `sharedValue` | `SharedValue` | `undefined` | Worklet-driven pre-formatted time string (e.g. `"14:30"`, `"2:30 PM"`). Mutually exclusive with direct time values. | Format props [#format-props] | Prop | Type | Default | Description | | ---------- | --------- | ------- | ------------------------------ | | `is24Hour` | `boolean` | `true` | Use 24-hour format. | | `padHours` | `boolean` | `true` | Pad hours with a leading zero. | Rendering props [#rendering-props] | Prop | Type | Default | Description | | ------------- | ------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `font` | `SkFont \| null` | **(required)** | Skia font instance from `useFont()` or `useSkiaFont()`. | | `color` | `string \| SharedValue` | `"#000000"` | Text color. Accepts a static string or a `SharedValue` for animated color transitions. | | `x` | `number` | `0` | X position within the Canvas. | | `y` | `number` | `0` | Y position (baseline). | | `width` | `number` | `0` | Available width for alignment. | | `textAlign` | `"left" \| "right" \| "center"` | `"left"` | Text alignment. | | `opacity` | `SharedValue` | `undefined` | Parent opacity for animation coordination. | | `tabularNums` | `boolean` | `false` | Force equal-width digits by interpolating between min and max digit glyph widths. Equivalent to `fontVariant: ['tabular-nums']` on native components. | Animation behavior props [#animation-behavior-props] All props from `AnimationBehaviorProps` are supported. See [NumberFlow](/docs/components/number-flow#animation-behavior-props) for details. Worklet Scrubbing [#worklet-scrubbing] Like `SkiaNumberFlow`, `SkiaTimeFlow` accepts a `sharedValue` for zero-latency UI thread updates: ```tsx import { Canvas } from '@shopify/react-native-skia'; import { useDerivedValue, useSharedValue } from 'react-native-reanimated'; import { SkiaTimeFlow, useSkiaFont } from 'number-flow-react-native/skia'; function ScrubbableTime() { const font = useSkiaFont('https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfMZg.ttf', 36); const totalSeconds = useSharedValue(3600); const formatted = useDerivedValue(() => { const h = Math.floor(totalSeconds.value / 3600); const m = Math.floor((totalSeconds.value % 3600) / 60); const s = Math.floor(totalSeconds.value % 60); return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`; }); return (

); } ``` Accessibility [#accessibility] Value changes are auto-announced via `AccessibilityInfo.announceForAccessibility`. For focus-based reading, set `accessibilityLabel` on the parent `Canvas`. # TimeFlow `TimeFlow` renders animated time displays with independently rolling hours, minutes, and seconds segments. It supports 12-hour and 24-hour formats, optional segments, countdown modes, and timestamp-based input. Import [#import] ```tsx import { TimeFlow } from 'number-flow-react-native'; ``` Basic Usage [#basic-usage] A live clock that updates every second: Props [#props] Time value props [#time-value-props] | Prop | Type | Default | Description | | ---------------- | --------------- | -------------- | ------------------------------------------------------------------------------------------------------------ | | `hours` | `number` (0–23) | `undefined` | Hours value. Omit to hide the hours segment (useful for MM:SS countdown mode). | | `minutes` | `number` (0–59) | **(required)** | Minutes value. | | `seconds` | `number` (0–59) | `undefined` | Seconds value. Omit to hide the seconds segment. | | `centiseconds` | `number` (0–99) | `undefined` | Centiseconds value. Omit to hide. Requires `seconds` to be set. Displayed as ".CC" after seconds. | | `timestamp` | `number` | `undefined` | Unix timestamp in milliseconds. Auto-extracts hours/minutes/seconds. Takes priority over direct value props. | | `timezoneOffset` | `number` | `undefined` | Timezone offset in milliseconds for timestamp mode. | Format props [#format-props] | Prop | Type | Default | Description | | ---------- | --------- | ------- | --------------------------------------------------------------------------------------------- | | `is24Hour` | `boolean` | `true` | Use 24-hour format. When `false`, displays 12-hour format. Only applies when hours are shown. | | `padHours` | `boolean` | `true` | Pad hours with a leading zero (`"09:30"` vs `"9:30"`). | Style props [#style-props] | Prop | Type | Default | Description | | ---------------- | ----------- | ----------- | ----------------------------------------------------------------------------------------- | | `style` | `TextStyle` | `undefined` | Text styling. `fontSize` defaults to `16` when omitted. `textAlign` defaults to `"left"`. | | `containerStyle` | `ViewStyle` | `undefined` | Style applied to the outer container `View`. | Animation behavior props [#animation-behavior-props] All props from `AnimationBehaviorProps` are supported: `trend`, `animated`, `respectMotionPreference`, `continuous`, `mask`, `transformTiming`, `spinTiming`, `opacityTiming`, `onAnimationsStart`, `onAnimationsFinish`. See [NumberFlow](/docs/components/number-flow#animation-behavior-props) for details. Examples [#examples] Countdown timer (MM:SS) [#countdown-timer-mmss] Omit `hours` to show minutes and seconds only: ```tsx import { useEffect, useState } from 'react'; import { View } from 'react-native'; import { TimeFlow } from 'number-flow-react-native'; function CountdownTimer({ initialSeconds = 300 }) { const [remaining, setRemaining] = useState(initialSeconds); useEffect(() => { if (remaining <= 0) return; const interval = setInterval(() => { setRemaining(prev => Math.max(0, prev - 1)); }, 1000); return () => clearInterval(interval); }, [remaining]); const mins = Math.floor(remaining / 60); const secs = remaining % 60; return ( ); } ``` 12-hour format [#12-hour-format] ```tsx {/* Renders: 2:30:00 */} ``` Timestamp with timezone offset [#timestamp-with-timezone-offset] ```tsx const tokyoOffset = 9 * 60 * 60 * 1000; // UTC+9 in ms ``` Accessibility [#accessibility] `TimeFlow` sets `accessibilityRole="text"` and an `accessibilityLabel` with the full formatted time string automatically. Screen readers read the complete time (e.g. "14:30:00") rather than announcing individual digit changes. # Basic Number The simplest `NumberFlow` usage: a number that rolls digit-by-digit when the value changes. # Constrained Digits The `digits` prop limits individual digit positions to custom ranges. Instead of the default 0–9 wheel, you can constrain a position to any maximum between 1–9. Here, every digit is constrained to `{ max: 1 }`, turning each position into a binary flip (0 or 1). Notes [#notes] * `{ max: 1 }` on every position creates a 2-element wheel (0, 1) instead of the default 10-element wheel (0–9). Each bit flips with a short, snappy roll. * The decimal value is converted to its binary representation via `parseInt(n.toString(2))`, then `minimumIntegerDigits: 8` pads to a full byte. `TimeFlow` automatically applies digit constraints internally (minutes tens: 0–5, hours tens: 0–2). The `digits` prop is for `NumberFlow` when you need custom constraints. # Continuous Mode Set `continuous={true}` to make unchanged lower-significance digits spin through a full rotation during transitions, creating an odometer-like effect. Notes [#notes] When `continuous` is enabled and a higher digit changes, lower digits that haven't changed still spin through a full 0–9 cycle. Going from `100` to `200`, the ones and tens digits both cascade through a complete rotation even though their final value hasn't changed. This creates the visual impression of the number "passing through" all intermediate values. # Countdown Timer A countdown timer using `TimeFlow` in MM:SS mode. Set `trend={-1}` to force all digits to always spin downward. Key points [#key-points] * Omitting `hours` hides the hours segment, giving a clean MM:SS display. * `trend={-1}` forces all digits to spin downward, matching the countdown direction. * The color changes to red when under 10 seconds remaining. # Currency Formatting `NumberFlow` accepts `Intl.NumberFormatOptions` via the `format` prop. Combined with `locales`, you get locale-specific currency symbols, decimal separators, and grouping, all animating independently. Key points [#key-points] * The `format` prop is passed directly to `Intl.NumberFormat`. Any option that works with `Intl.NumberFormat` works here. * When switching currencies, symbols like `$`, `€`, and `¥` animate in and out with opacity and vertical slide transitions. * The `locales` prop controls grouping separators (`1,234.56` in `en-US` vs `1.234,56` in `de-DE`) and currency symbol placement. # Non-Latin Numerals The library auto-detects the numeral system from the `locales` and `format` props and renders the appropriate Unicode digits. 37 numeral systems are supported. Notes [#notes] * The numeral system is detected via `detectNumberingSystem()` from the locale and format options. * `getDigitStrings()` returns the Unicode digit characters for that system (e.g. `['٠','١','٢','٣','٤','٥','٦','٧','٨','٩']` for Arabic-Indic). * Digit wheels render the locale-appropriate characters, and the adaptive mask adjusts to each character's glyph bounds. * Grouping separators and decimal marks also follow the locale (e.g. `٬` as thousands separator in Arabic). Supported systems [#supported-systems] | System | Script | Digits (0–9) | Locale | | ---------- | --------------------- | ------------ | ------------------------ | | `arab` | Arabic-Indic | ٠١٢٣٤٥٦٧٨٩ | `ar-SA` | | `arabext` | Extended Arabic-Indic | ۰۱۲۳۴۵۶۷۸۹ | `fa-IR` | | `bali` | Balinese | ᭐᭑᭒᭓᭔᭕᭖᭗᭘᭙ | `*-u-nu-bali` | | `beng` | Bengali | ০১২৩৪৫৬৭৮৯ | `bn-BD` | | `cham` | Cham | ꩐꩑꩒꩓꩔꩕꩖꩗꩘꩙ | `*-u-nu-cham` | | `deva` | Devanagari | ०१२३४५६७८९ | `mr-IN` or `*-u-nu-deva` | | `fullwide` | Fullwidth | ０１２３４５６７８９ | `*-u-nu-fullwide` | | `gujr` | Gujarati | ૦૧૨૩૪૫૬૭૮૯ | `*-u-nu-gujr` | | `guru` | Gurmukhi | ੦੧੨੩੪੫੬੭੮੯ | `*-u-nu-guru` | | `hanidec` | Chinese Decimal | 〇一二三四五六七八九 | `*-u-nu-hanidec` | | `java` | Javanese | ꧐꧑꧒꧓꧔꧕꧖꧗꧘꧙ | `*-u-nu-java` | | `kali` | Kayah Li | ꤀꤁꤂꤃꤄꤅꤆꤇꤈꤉ | `*-u-nu-kali` | | `khmr` | Khmer | ០១២៣៤៥៦៧៨៩ | `*-u-nu-khmr` | | `knda` | Kannada | ೦೧೨೩೪೫೬೭೮೯ | `*-u-nu-knda` | | `lana` | Tai Tham Hora | ᪀᪁᪂᪃᪄᪅᪆᪇᪈᪉ | `*-u-nu-lana` | | `lanatham` | Tai Tham Tham | ᪐᪑᪒᪓᪔᪕᪖᪗᪘᪙ | `*-u-nu-lanatham` | | `laoo` | Lao | ໐໑໒໓໔໕໖໗໘໙ | `*-u-nu-laoo` | | `latn` | Latin | 0123456789 | `en-US` (default) | | `lepc` | Lepcha | ᱀᱁᱂᱃᱄᱅᱆᱇᱈᱉ | `*-u-nu-lepc` | | `limb` | Limbu | ᥆᥇᥈᥉᥊᥋᥌᥍᥎᥏ | `*-u-nu-limb` | | `mlym` | Malayalam | ൦൧൨൩൪൫൬൭൮൯ | `*-u-nu-mlym` | | `mong` | Mongolian | ᠐᠑᠒᠓᠔᠕᠖᠗᠘᠙ | `*-u-nu-mong` | | `mtei` | Meetei Mayek | ꯰꯱꯲꯳꯴꯵꯶꯷꯸꯹ | `*-u-nu-mtei` | | `mymr` | Myanmar | ၀၁၂၃၄၅၆၇၈၉ | `my-MM` | | `mymrshan` | Myanmar Shan | ႐႑႒႓႔႕႖႗႘႙ | `*-u-nu-mymrshan` | | `nkoo` | N'Ko | ߀߁߂߃߄߅߆߇߈߉ | `*-u-nu-nkoo` | | `olck` | Ol Chiki | ᱐᱑᱒᱓᱔᱕᱖᱗᱘᱙ | `sat-IN` | | `orya` | Odia | ୦୧୨୩୪୫୬୭୮୯ | `*-u-nu-orya` | | `saur` | Saurashtra | ꣐꣑꣒꣓꣔꣕꣖꣗꣘꣙ | `*-u-nu-saur` | | `sinh` | Sinhala Lith | ෦෧෨෩෪෫෬෭෮෯ | `*-u-nu-sinh` | | `sund` | Sundanese | ᮰᮱᮲᮳᮴᮵᮶᮷᮸᮹ | `*-u-nu-sund` | | `talu` | New Tai Lue | ᧐᧑᧒᧓᧔᧕᧖᧗᧘᧙ | `*-u-nu-talu` | | `tamldec` | Tamil | ௦௧௨௩௪௫௬௭௮௯ | `*-u-nu-tamldec` | | `telu` | Telugu | ౦౧౨౩౪౫౬౭౮౯ | `*-u-nu-telu` | | `thai` | Thai | ๐๑๒๓๔๕๖๗๘๙ | `*-u-nu-thai` | | `tibt` | Tibetan | ༠༡༢༣༤༥༦༧༨༩ | `dz-BT` | | `vaii` | Vai | ꘠꘡꘢꘣꘤꘥꘦꘧꘨꘩ | `*-u-nu-vaii` | `*` means any base locale. For example, `en-US-u-nu-thai` gives Thai digits with English formatting (commas as group separators), while `th-TH-u-nu-thai` gives Thai digits with Thai formatting conventions. # Percentage & Compact Notation `NumberFlow` supports all `Intl.NumberFormat` notation styles. This example shows `style: 'percent'` and `notation: 'compact'`. Percentage [#percentage] `style: 'percent'` multiplies the value by 100 and appends `%`. Pass `0.42` to display `42.0%`. Compact Notation [#compact-notation] `notation: 'compact'` abbreviates large numbers with locale-appropriate suffixes like `K`, `M`, `B`. The suffix characters animate in and out as the magnitude changes. Compact notation suffixes are locale-dependent. For example, `en-US` uses "K", "M", "B" while `ja-JP` uses "万", "億". # Prefix & Suffix The `prefix` and `suffix` props add static text that animates in and out alongside the number. Useful for labels, units, and decorative text. Notes [#notes] * Prefix and suffix characters are treated as static symbols in the layout engine. * When a prefix or suffix is added or removed (e.g. changing from `""` to `"Score: "`), each character enters with an opacity + vertical slide animation. * Prefix/suffix characters are keyed independently, so changing from `" pts"` to `" points"` animates only the differing characters. # Right-to-Left (RTL) In RTL apps, `NumberFlow` automatically right-aligns numbers and applies Unicode bidi visual reordering so currency symbols, minus signs, and other formatting elements appear on the correct side. This works out of the box when `I18nManager.isRTL` is `true`, or you can set `direction="rtl"` explicitly. How it works [#how-it-works] In a standard RTL React Native app, `I18nManager.isRTL` is `true` and NumberFlow adapts automatically: * **Default alignment** changes to right (the "start" edge in RTL) * **Bidi visual reordering** repositions currency symbols and signs to match browser text rendering. Arabic `١٬٢٣٤٫٥٦ ج.م.` becomes `ج.م. ١٬٢٣٤٫٥٦` (currency on the left, the visual "start" in RTL) * **Digits stay left-to-right** within the number block, matching how numbers are read universally The reordering is driven by the bidi control marks that `Intl.NumberFormat` embeds in its output. Arabic and Hebrew formats start with RLM (Right-to-Left Mark), triggering reordering. Persian formats start with LRM (Left-to-Right Mark), keeping their logical order. For per-component control (e.g. an LTR number inside an RTL app), pass `direction` explicitly: ```tsx ``` The `textAlign` style also supports `"start"` and `"end"` which resolve based on direction: ```tsx // "start" = left in LTR, right in RTL ``` Affected locales [#affected-locales] Bidi reordering activates for locales whose `Intl.NumberFormat` output contains RTL directional marks. This includes all locales using Arabic or Hebrew script: | Locale | Script | Currency position | Negative format | | ------------------------- | ------------------- | ------------------ | ------------------------ | | `ar-EG` (Arabic, Egypt) | Arabic-Indic digits | `ج.م.` moves left | minus on right of digits | | `ar-SA` (Arabic, Saudi) | Arabic-Indic digits | `ر.س.` moves left | minus on right of digits | | `he-IL` (Hebrew, Israel) | Latin digits | `₪` moves left | minus stays with digits | | `ar-MA` (Arabic, Morocco) | Latin digits | varies by currency | minus on right of digits | Some RTL-script locales use LRM marks in their format output, which prevents reordering. Their logical order already matches the visual order: | Locale | Script | Behavior | | ------------------------ | --------------------- | -------------------------- | | `fa-IR` (Persian, Iran) | Extended Arabic-Indic | No reorder (LRM in format) | | `ur-PK` (Urdu, Pakistan) | Latin digits | No reorder (LRM in format) | The bidi reordering is a simplified implementation of the Unicode Bidirectional Algorithm (UAX #9), scoped to the character types present in formatted numbers. It produces the same visual order as a browser's native text rendering for all standard `Intl.NumberFormat` output. # Scientific & Engineering Notation `NumberFlow` supports scientific and engineering notation via `Intl.NumberFormat`. Exponents are rendered automatically as superscripts at 60% scale. They are also animated independently, so changes to the exponent (e.g. `E23` → `E24`) roll correctly! Notes [#notes] * The exponent part (e.g. `E23`) is detected during formatting and rendered at 60% of the base font size using a pivot-scale transform. * Exponent digits roll independently, just like the mantissa digits. * Engineering notation constrains exponents to multiples of 3 (e.g. `6.022E23` → `602.2E21` in engineering). # Skia Basic `SkiaNumberFlow` renders inside a Skia `Canvas` and requires a loaded `SkFont`. Use `useSkiaFont` for a guaranteed non-null font with system-font fallback. Key differences from NumberFlow [#key-differences-from-numberflow] * Must be wrapped in a Skia `Canvas` * Requires a `SkFont` (custom font file) instead of system fonts * Positioned with `x`, `y`, `width` instead of `style` and `containerStyle` * Color is a string prop, not part of `style` * Supports `sharedValue` for worklet-driven scrubbing # Skia Worklet Scrubbing The `sharedValue` prop on `SkiaNumberFlow` enables worklet-driven rendering - the number display updates entirely on the UI thread without crossing the JS bridge. This means updates at 120Hz with zero frame drops. How scrubbing works [#how-scrubbing-works] 1. You provide a `SharedValue`, a pre-formatted string like `"50.0"` or `"$1,234.56"`. 2. On the UI thread, the worklet reads the string, extracts digits, and drives Skia rendering directly. 3. `useScrubbingBridge` periodically syncs the digit count back to the JS thread so React can update the layout (number of slots). 4. `useScrubbingLayout` computes per-slot positions from the worklet string. The `scrubDigitWidthPercentile` prop (default: `0.75`) controls how wide each digit slot is during scrubbing. Since digit values change rapidly during gestures, the component needs a fixed width per slot. The percentile picks a width between the narrowest (`0`) and widest (`1`) digit glyph. # Time Display `TimeFlow` renders animated HH:MM:SS displays with independently rolling digit segments. It auto-constrains digits (tens of minutes: 0–5, tens of hours: 0–2) for correct clock behavior. Segment visibility [#segment-visibility] * **Full time:** Pass `hours`, `minutes`, and `seconds` (or use `timestamp`) * **Hours + minutes:** Pass `hours` and `minutes`, omit `seconds` * **Minutes + seconds:** Omit `hours`, pass `minutes` and `seconds` # Trend Control The `trend` prop controls which direction digits spin during transitions. You can pass a static value or a function for dynamic control. Trend values [#trend-values] | Value | Behavior | | --------------------- | -------------------------------------------------------------------------------------------------------- | | `undefined` (default) | Auto-detects: increasing values spin up, decreasing spin down | | `1` | Always spin upward | | `-1` | Always spin downward | | `0` | Each digit takes the shortest path (e.g. 9→1 goes up through 0 instead of rolling down through 8,7,6...) | Dynamic trend function [#dynamic-trend-function] You can also pass a function that receives the previous and next values: ```tsx { if (next > prev) return 1; // Price up → spin up if (next < prev) return -1; // Price down → spin down return 0; // Same → shortest path }} style={{ fontSize: 36, color: '#fff' }} /> ``` # useCanAnimate Returns whether NumberFlow animations are currently enabled, based on the device's "Reduce Motion" accessibility setting. Import [#import] ```tsx import { useCanAnimate } from 'number-flow-react-native'; ``` Signature [#signature] ```tsx useCanAnimate(respectMotionPreference?: boolean): boolean ``` Parameters [#parameters] | Parameter | Type | Default | Description | | ------------------------- | --------- | ------- | ------------------------------------------------------------------------ | | `respectMotionPreference` | `boolean` | `true` | When `true`, returns `false` if the device "Reduce Motion" setting is on | Returns [#returns] `boolean`: `true` if animations should play, `false` if reduced motion is active. Usage [#usage] ```tsx import { Text } from 'react-native'; import { NumberFlow } from 'number-flow-react-native'; import { useCanAnimate } from 'number-flow-react-native'; function AnimatedPrice({ value }: { value: number }) { const canAnimate = useCanAnimate(); if (!canAnimate) { return ${value.toFixed(2)}; } return ( ); } ``` NumberFlow components already respect Reduce Motion internally via the `respectMotionPreference` prop (default: `true`). This hook is mainly useful when you need to conditionally render entirely different UI based on motion capability. Implementation [#implementation] Under the hood, `useCanAnimate` uses Reanimated's `useReducedMotion` to read the device accessibility setting. When `respectMotionPreference` is `false`, the hook always returns `true` regardless of the device setting. # useFormattedValue Formats a numeric value to a display string using `Intl.NumberFormat`. Useful for providing accessibility labels on Skia `Canvas` components, which don't have built-in text semantics. Import [#import] ```tsx import { useFormattedValue } from 'number-flow-react-native'; ``` Signature [#signature] ```tsx useFormattedValue( value: number | undefined, format?: Intl.NumberFormatOptions, locales?: Intl.LocalesArgument, prefix?: string, suffix?: string, ): string | undefined ``` Parameters [#parameters] | Parameter | Type | Description | | --------- | -------------------------- | -------------------------------------------------------- | | `value` | `number \| undefined` | Numeric value to format | | `format` | `Intl.NumberFormatOptions` | Optional formatting options | | `locales` | `Intl.LocalesArgument` | Optional locale(s) for formatting | | `prefix` | `string` | Optional static prefix prepended to the formatted string | | `suffix` | `string` | Optional static suffix appended to the formatted string | Returns [#returns] `string | undefined`: the formatted string, or `undefined` if `value` is `undefined`. Usage [#usage] The primary use case is adding accessibility to Skia-rendered numbers. Since `Canvas` is an opaque view to the accessibility system, you need to provide a label manually: ```tsx import { Canvas } from '@shopify/react-native-skia'; import { useFormattedValue } from 'number-flow-react-native'; import { SkiaNumberFlow, useSkiaFont } from 'number-flow-react-native/skia'; function Price({ value }: { value: number }) { const font = useSkiaFont(require('./Inter.ttf'), 32); const format = { style: 'currency', currency: 'USD' } as const; const label = useFormattedValue(value, format); return (

); } ``` `useFormattedValue` uses `Intl.NumberFormat` internally with the same formatter cache as the components, so passing identical `format` and `locales` options does not create duplicate formatter instances. # useSkiaFont Loads a custom Skia font asynchronously while providing a synchronous system-font fallback via `matchFont`. Guarantees a non-null `SkFont` from the very first render, so components can run the full animated pipeline immediately instead of showing a blank canvas. Import [#import] ```tsx import { useSkiaFont } from 'number-flow-react-native/skia'; ``` Signature [#signature] ```tsx useSkiaFont(source: DataSourceParam, size: number, onError?: (err: Error) => void): SkFont ``` Parameters [#parameters] | Parameter | Type | Description | | --------- | ---------------------- | ------------------------------------------------- | | `source` | `DataSourceParam` | Font asset reference (`require()` or URI) | | `size` | `number` | Font size in points | | `onError` | `(err: Error) => void` | Optional error callback for font loading failures | Returns [#returns] `SkFont` is always non-null. Returns a system font fallback until the custom font loads. Usage [#usage] ```tsx import { Canvas } from '@shopify/react-native-skia'; import { SkiaNumberFlow, useSkiaFont } from 'number-flow-react-native/skia'; function PriceDisplay() { const font = useSkiaFont(require('./assets/Inter.ttf'), 32); return (

); } ``` Once the custom font loads, `SkiaNumberFlow` automatically animates from the system font metrics to the custom font metrics, with no loading state needed. vs. useFont [#vs-usefont] Skia's built-in `useFont` returns `null` while the font is loading, which means `SkiaNumberFlow` renders an empty canvas until the font is ready. `useSkiaFont` solves this by calling `matchFont()` to create an immediate system-font fallback at the requested size: * **First render:** system font from `matchFont({ fontSize: size })` * **After load:** custom font from `useFont(source, size)` Your animated numbers are visible and interactive from the very first frame, with no conditional rendering or loading placeholders required. # Accessibility The library has built-in accessibility support for screen readers and motion preferences. Screen reader support [#screen-reader-support] Native components (NumberFlow, TimeFlow) [#native-components-numberflow-timeflow] Native components automatically set: * `accessibilityRole="text"`: tells VoiceOver/TalkBack this is a text element * `accessibilityLabel`: the full formatted value (e.g. "$42.99", "14:30:00") Screen readers read the complete formatted number rather than announcing individual digit changes. No additional setup needed. Skia components (SkiaNumberFlow, SkiaTimeFlow) [#skia-components-skianumberflow-skiatimeflow] Skia components render on a Canvas, which is opaque to the accessibility system. They handle accessibility in two ways: 1. **Auto-announcements**: Value changes are announced via `AccessibilityInfo.announceForAccessibility()`. This works for dynamic updates, but not for initial focus. 2. **Focus-based reading**: For VoiceOver/TalkBack to read the value when the user focuses the element, set `accessibilityLabel` on the parent `Canvas`: ```tsx import { Canvas } from '@shopify/react-native-skia'; import { useFormattedValue } from 'number-flow-react-native'; import { SkiaNumberFlow, useSkiaFont } from 'number-flow-react-native/skia'; function AccessibleSkiaPrice({ value }: { value: number }) { const font = useSkiaFont(require('./Inter.ttf'), 32); const format = { style: 'currency', currency: 'USD' } as const; const label = useFormattedValue(value, format); return (

); } ``` Reduce Motion [#reduce-motion] respectMotionPreference prop [#respectmotionpreference-prop] All four components accept `respectMotionPreference` (default: `true`). When enabled and the device's "Reduce Motion" setting is on, animations are disabled and values update instantly. ```tsx // Animations disabled when Reduce Motion is on (default behavior) // Force animations regardless of Reduce Motion ``` useCanAnimate hook [#usecananimate-hook] For cases where you want to conditionally render entirely different UI: ```tsx import { useCanAnimate } from 'number-flow-react-native'; function Price({ value }: { value: number }) { const canAnimate = useCanAnimate(); if (!canAnimate) { return ${value.toFixed(2)}; } return ; } ``` Best practices [#best-practices] * **Native components**: No action needed, accessibility is automatic * **Skia components**: Always set `accessibilityLabel` on the parent `Canvas` using `useFormattedValue` * **Prefix/suffix** (NumberFlow only): These are included in the generated accessibility label automatically * **TimeFlow**: The label includes the full time string (e.g. "14:30:00"), including AM/PM for 12-hour formats * **Don't disable motion preferences** without a strong reason, `respectMotionPreference={false}` should be rare # Performance Tips You shouldn't need to think about performance in most cases, since the library handles the heavy lifting internally. This page covers what's already optimized for you, how to choose between the renderers and update modes, and a few situations where you can help. What's already handled [#whats-already-handled] Format object caching [#format-object-caching] You don't need to worry about passing inline `format` objects. The library serializes format options via `JSON.stringify` internally, so structurally identical objects won't trigger extra work even if their reference changes on every render: ```tsx function Price({ value }: { value: number }) { return ( ); } ``` `Intl.NumberFormat` instances are also cached globally, so multiple components with the same format share a single formatter. That said, defining format objects as constants is still good practice for readability: ```tsx const currencyFormat = { style: 'currency', currency: 'USD' } as const; ``` Style objects and parent re-renders [#style-objects-and-parent-re-renders] Inline `style` objects are stabilized by content, so a parent re-render (or a new object literal on every render) doesn't re-render any digit slots. When the value changes, only the slots whose digits actually changed commit; the rest bail out. Wrapping `NumberFlow` in `React.memo` is not necessary. ```tsx // Fine: neither the inline style nor parent re-renders reach the slots ``` One animated node per digit wheel [#one-animated-node-per-digit-wheel] The native renderer animates each rolling digit column as a single translated strip, so a spinning slot costs one animated style update per frame regardless of how many digits the wheel holds. Glyph metrics are measured once per font and shared across all components using it, in both renderers. Progressive mount (Native renderer) [#progressive-mount-native-renderer] Native components (`NumberFlow`, `TimeFlow`) render a plain `Text` element on the first frame, then swap to the full animated slot tree on the next frame via `requestAnimationFrame`. This avoids the cost of instantiating all the animated hooks during the initial mount, so the component appears instantly without a blank flash. Skia components don't need this, since canvas rendering doesn't have the same view hierarchy overhead. Reduce Motion [#reduce-motion] When the device's "Reduce Motion" setting is on (and `respectMotionPreference` is `true`, which is the default), all animation durations collapse to zero. Transitions become instant; values snap to their final position without interpolation across multiple frames. Choosing a renderer and update mode [#choosing-a-renderer-and-update-mode] The renderers have different scaling behavior under load. As a rule of thumb: * **A handful of components, occasional updates:** either renderer. The native renderer runs a single ticking component at full frame rate. * **Many components animating at once (dashboards, tables, price grids):** prefer `SkiaNumberFlow` inside a single `Canvas`. One canvas drawing many numbers keeps the UI thread at full frame rate where the equivalent native view trees start dropping frames. * **High-frequency updates (gestures, sensors, timers at \~100ms or faster), especially across many components:** use `SkiaNumberFlow` with the `sharedValue` prop. This is the only mode whose per-update cost does not go through React at all. The reason `sharedValue` mode exists is structural. When the `value` prop changes, React commits, and React Native Skia re-records the canvas's drawing tree and hands it to the UI runtime synchronously on the JS thread. That cost is per canvas, per commit. It is cheap in isolation, but it grows with the number of canvases and the update rate: profiling a grid of 30 Skia components ticking at 10Hz shows the JS thread spending most of its time in that synchronous handoff, falling behind the tick rate even while the UI thread renders at a steady frame rate. Driving the same workload through `sharedValue` produces zero React commits per update, so none of that work happens. ```tsx const formatted = useDerivedValue(() => `${speed.value.toFixed(0)}`); ``` Note that `sharedValue` expects a `SharedValue` (a pre-formatted string), not a number. You're responsible for formatting in the worklet. In this mode, the library pre-allocates a pool of 20 `SharedValue` slots at mount time. Digit extraction happens entirely on the UI thread via `useAnimatedReaction`, writing directly to these pre-allocated values without crossing the JS bridge. When you should optimize [#when-you-should-optimize] Timing config objects [#timing-config-objects] Unlike format objects, `transformTiming`, `spinTiming`, and `opacityTiming` are plain objects compared by reference. If you're defining custom timings, keep them outside the component to avoid unnecessary re-renders of the internal slot components: ```tsx import { Easing } from 'react-native-reanimated'; const timing = { duration: 600, easing: Easing.out(Easing.cubic) }; function Price({ value }: { value: number }) { return ; } ``` # Troubleshooting iOS linker error: DebugStringConvertible / Sealable undefined symbols (RN 0.84+) [#ios-linker-error-debugstringconvertible--sealable-undefined-symbols-rn-084] On React Native 0.84 and newer, iOS links against a prebuilt React core framework by default. Its Release flavor is compiled with `NDEBUG`, which removes debug-only C++ symbols like `facebook::react::DebugStringConvertible` and `facebook::react::Sealable`. When the prebuilt core on disk doesn't match your build configuration (stale `Pods/` state, an interrupted build, or a CocoaPods cache carrying over an old extraction), every Fabric library built from source fails to link with errors like: ``` Undefined symbols for architecture arm64: "facebook::react::Sealable::Sealable()", referenced from: facebook::react::NFMaskedViewProps::NFMaskedViewProps() in libNFMaskedView.a(NFMaskedViewComponentView.o) ``` This is not specific to `@rednegniw/masked-view`: the same error hits any from-source Fabric component (it's just often the first one in an otherwise JS-only app). To fix it, reset the pods state so the correct core flavor is re-extracted: ```bash cd ios rm -rf Pods build pod install ``` Then clean the build folder in Xcode (Product > Clean Build Folder) and rebuild. Don't work around this by defining `REACT_NATIVE_PRODUCTION=1` in your Podfile. It silences the linker error but creates an ABI mismatch in `ViewProps` that crashes at runtime. Also make sure your Podfile calls `react_native_post_install(installer, ...)` in `post_install`; it aligns compiler flags with the prebuilt core in Release builds. # Apple Stopwatch An Apple Stopwatch replica using `TimeFlow` with the `centiseconds` prop for a single-component `MM:SS.CC` display. The `centiseconds` prop on `TimeFlow` renders a `.CC` segment after seconds using fixed keys (`c10`, `c1`) for stable animations. Combined with `fontVariant: ['tabular-nums']`, this creates a jitter-free stopwatch display with a single component, with no need to compose multiple `NumberFlow` instances. # Countdown App A space-themed countdown with dramatic Mars imagery, Orbitron typography, and large animated digits ticking toward touchdown. This demo uses a CSS `linear-gradient` for the image-to-background fade. Since `LiveExample` demos run as React Native Web in the browser, CSS properties like `background` work directly in the `style` prop. In a real React Native app, you'd use `expo-linear-gradient` or `react-native-linear-gradient` instead. # Step Counter A Galaxy Watch-inspired step counter with a circular progress arc, auto-incrementing step count with the signature `continuous` odometer roll, and dynamic weekday activity indicators. The circular progress ring uses the SVG `strokeDasharray`/`strokeDashoffset` technique. A 240-degree partial arc is created by setting the dash array to the arc length and gap length, then `strokeDashoffset` controls how much of the arc is filled. With a CSS transition on the offset, the ring animates smoothly in sync with `NumberFlow`'s digit roll as steps tick up. # Trading Ticker An Apple Stocks-inspired ticker with dual animated values. Both the stock price and day change roll their digits in sync, with inline SVG sparkline charts colored by trend direction. Notice that `trendFn`, `priceFormat`, and `changeFormat` are declared outside the component as stable references, since creating new function/object identities every render would trigger unnecessary work inside `NumberFlow`. The `signDisplay: 'exceptZero'` format option handles the `+`/`-` prefix automatically via `Intl.NumberFormat`, so the sign itself becomes an animated character in the digit roll.