NitroNumber props
NitroNumber accepts every View prop (style, testID, accessibilityLabel, …) plus the following. All are optional except value.
Value and formatting
valuenumberThe number to display. Every change rolls each digit natively. At most 18 digits are shown: |value| × 10^fractionDigits is clamped at 10^17, and a JS number carries exact integers only up to 2^53.
Digits after the decimal separator (0–9).
Zero-pads the integer part (1–15).
Inserted between digit groups (every three, unless groupingSizes says otherwise).
Digit group sizes counted from the decimal point: the first group, then every later one. [3, 2] is Indian grouping (12,34,567), [2, 0] one separator two digits in. A format gives its locale's.
Between integer and fraction digits.
Static text around the number.
Which values carry a sign, as Intl.NumberFormat's: 'always' and 'exceptZero' put a plus on gains ("+$12.40"), and a plus that turns into a minus swaps like any other glyph. A value that rounds to zero at the shown fraction digits counts as zero, so -0.001 shows no minus. A format gives its own.
The glyphs drawn for the signs, e.g. '−' (U+2212, the typographic minus). A format gives its locale's minus.
digitGlyphsstring[]The ten glyphs drawn for 0 to 9, for native digits: ['٠','١','٢','٣','٤','٥','٦','٧','٨','٩']. A format with another numbering system (ar-EG, hi-IN-u-nu-deva) gives its own.
digitsRecord<number, { max: number }>The highest digit an integer position (0 the ones, 1 the tens…) shows before it wraps to 0, as NumberFlow's digits. { 1: { max: 5 } } makes the tens of a clock's seconds wrap after 5, so 59 → 00 turns them one step instead of five back. NitroTime sets it for you.
Roll timing
false shows every change at once, a reveal included; the flash and the pop still play.
Snap while the system's Reduce Motion is on. false animates regardless, for a figure whose motion carries meaning.
Rolls turn the wheels below the highest one that changes a full turn too, in the direction of the change, so 100 → 200 seems to pass through every value between (NumberFlow's continuous). Rolls only.
Roll duration in ms; 0 snaps.
Roll timing curve. A value that arrives mid-roll continues with the ease-out half of the curve, so rapid updates never stall.
Overshoot of the spring easing (0–1).
ms between the start of each digit's roll, least significant first (a cascading carry). In the numeric transition the cascade runs from the leftmost digit to the right instead; its default there is 50.
How a value change plays; see the transitions. roll is the odometer: every changed digit rolls through the digits between its old and new glyph. numeric is the effect of SwiftUI's .contentTransition(.numericText()): each changed glyph swaps in place, the old one softening, shrinking and sliding out while the new one slides in from the other side and comes into focus, the digits cascading from the left; unchanged digits stay put. scramble shows a different random digit every few frames until each changed digit locks on its target, from the left. Each swap style has its own defaults for duration, easing and stagger: numeric 480 ms with SwiftUI's own clocks (easing and bounce are not consulted) and a 150 ms cascade span as stagger, scramble 500 / linear / 60.
flashUpColor, flashDownColorColorValueThe change flash: every digit whose glyph changes lights up in flashUpColor when the value grew and flashDownColor when it shrank (a green and a red, say), stays lit while it moves, and fades back over flashDuration once it has landed. Unset: no flash. Works with every transition, and under Reduce Motion, where the digits change at once but still light up.
Milliseconds a change flash takes to fade, once the digit has landed.
A punch of the whole figure on every value change, its peak overshoot as a fraction of the size, 0 (none) to 1, rung out like the reveal's landing pop. 0.08 is a nudge, 0.2 a slam.
Roll direction; auto follows the sign of the change, up and down force one. shortest rolls each digit its own shorter way round: 1 → 2 is one step up even when the value falls, where auto rolls nine steps down, which keeps a big jump calm. The numeric transition and the reveal ignore it.
Jackpot reveal
See Jackpot reveal.
revealbooleanfalse holds the opening frame ($0.00 in the final layout); true plays the reveal to value. undefined = a normal NitroNumber.
The win-meter rollup, or the slot reels locking from the left.
ms of the count, or until the last reel locks.
Peak overshoot of the landing pop and the milestone punches; 0 = none.
count: how much smaller the figure opens (a fraction of its size), growing to full size over the count.
spin: ms between reel stops, shortened to fit the duration.
revealMilestonesnumber[]count: tiers in the figure's units. The count lands on each, punches, holds, then accelerates again.
count: ms the count pauses on each milestone.
onRevealMilestone(index, value) => voidThe count reached a milestone.
onRevealEnd() => voidThe reveal landed (count or reels done, pop rung out).
Loading
Shine glint: a slanted, text-wide band sweeps through the ink; cross-fades on toggle.
Color of the glint's core (#D6D9E1, #2B2E37 in dark mode).
ms per sweep (linear, repeating).
The band's slant in degrees: 0 upright, positive leans it like "/", negative the other way (up to ±75).
The band's width as a fraction of the number's: 0.35 is a narrow glint, 1.5 a slow wash.
The glyphs' colour outside the band while loading. A light grey turns the figure into a skeleton that the band lights up; pair it with a darker shimmerColor.
Which way the band sweeps; 'auto' follows the layout direction. 'rtl' mirrors the slant too.
ms the band waits off the far edge after each sweep.
Typography and layout
Font size of the digits in points.
Smaller (or larger) prefix / suffix.
How prefix / suffix line up with the digits: top pins the glyph tops (cap height), bottom the bottom of the glyphs' ink (the digits' baseline).
Per-affix override.
Points added after every glyph, like Text's letterSpacing (negative tightens). A smaller prefix or suffix gets it in proportion to its size.
Points between the prefix and the digits, and between the digits and the suffix, in place of the letter spacing there.
Points an affix is moved down after its alignment places it (negative: up), for a symbol that sits a little off every preset.
The affixes' colours: a muted currency symbol or unit.
The fraction digits' and decimal separator's size: smaller cents.
The fraction digits' and decimal separator's colour: dimmer cents.
How smaller fraction digits line up with the integer ones; 'top' sets superscript cents ("$12⁹⁹").
Every digit as wide as the widest, so columns never move. false lays each digit out at its own width (the font's proportional figures), for a face whose "1" is narrow or that has no tabular figures; a changing column's width eases once from the old digit's to the new one's, and a reveal keeps its target's widths throughout.
formatNumberFormatA NumberFormat the number follows: its prefix and suffix (the currency where the locale puts it), grouping separator and group sizes, decimal separator, fraction digits, minimum integer digits, sign display and minus sign, and its numbering system's digits. A compact format (notation: 'compact') rolls the figure it shows and swaps its suffix as the value crosses a thousand, a million: "950" → "1.5K" → "2.3M". The individual props override what it says.
Shrink the whole number to fit the view's width; the view keeps its full height.
Lower bound for adjustsFontSizeToFit.
Follow the system text size like Text.
Cap for allowFontScaling; 0 = no cap.
Font weight.
Font family, resolved like Text.
Text color.
Alignment inside a wider frame. 'auto' is the start edge of the layout direction, as Text, except in a view that hugs the number: there it is the edge the parent keeps the view to, so a figure at the end of a row (justifyContent: 'space-between') grows and shrinks from its right edge instead of jumping. 'left' and 'right' are absolute. In a right-to-left app the prefix sits at the right edge and the suffix at the left, and the digits keep reading left to right; a single figure can be flipped with style={{ direction: 'rtl' }}.
onAnimationStart() => voidCalled when the figure starts moving from rest: a change, or a reveal.
onAnimationEnd(value: number) => voidCalled when the figure comes to rest, with the value it shows: once for a run of changes that arrived while it was moving. A snapped change (animated={false}, Reduce Motion, duration={0}) fires neither. With a compact format the value is the value, not the figure the digits show.
onNativeRef(ref) => voidReceives the Nitro object on mount.
Methods (ref)
| Method | Description |
|---|---|
animateTo(value) | Rolls to value, like changing the prop. |
jumpTo(value) | Positions the wheels continuously from value (odometer carry rule), no roll. Skips a running reveal. |
revealTo(value) | Plays a jackpot reveal to value in the current revealStyle. |
getValue() | The value shown or being rolled towards. |
native | The Nitro object, or null before mount. |
All methods are safe to call from any thread and coalesce to the newest value per frame.