Pricing

NumberFlow handbook

v2.1.0 · @snowui-design-system/components

License: Before reading component documentation, source, or npm usage instructions for the first time, read the full LICENSE. Reuse that review for the same task and version. Public API configuration and internal implementation changes have different license implications. All components use the unified runtime package; source rights remain governed by the license.

Overview

Animate number changes with digit-by-digit rolling and width transitions while preserving currency, grouping separators, and decimals. Suitable for counters and live metrics.

When to use it

Use NumberFlow for rolling digits. Compare NumericText for other numeric transitions. Use Text for static values without motion.

  • value is the number; unparseable strings display as 0. locales and format control formatting.

  • children add content before or after the number. Enable respectMotionPreference explicitly to honor the system’s reduced-motion setting.

Quick start

This example shows the recommended basic composition. See the sections below for more cases and composition limits.

<script lang="ts">	import { Button, Text } from '@snowui-design-system/components';	import { NumberFlow, chromatic } from '@snowui-design-system/components';	let count = $state(0);</script> <div style="display: flex; flex-direction: column; align-items: center; gap: var(--gap-4);">	<NumberFlow value={count} format={{ useGrouping: true }} motionRole="number" motionColor={chromatic()} size="--text-48" lineHeight="--leading-48" weight={600} />	<div style="display: flex; align-items: center; gap: var(--gap-2);">		<Button aria-label="Decrease installs" onclick={() => count -= 128}>−128</Button>		<Button aria-label="Increase installs" onclick={() => count += 128}>+128</Button>		<Button onclick={() => count = 0}>Reset</Button>	</div></div>

API

Keyword Type Default Description
value number | string — Current value; unparseable strings are treated as 0.
locales string "en-US" Locale passed to Intl.NumberFormat.
format Intl.NumberFormatOptions {} Number formatting options.
trend TrendResolver 0 Explicit direction of change; 0 derives it from the previous and next values.
motionRole TextMotionRole "auto" The semantic role of numerical trend
transition NumberFlowTransition — Override the digit-wheel duration.
digits Record<number, { max?: number }> — Set the wrap limit for a digit position, such as the tens digit of a clock.
numberPosition "left" | "right" "right" children relative position of numbers
rollDirection RollDirection "normal" Interpret the direction of change normally or in reverse.
loading boolean — Display the Skeleton derived from the current text width
skeleton boolean — Participate in Skeleton Context.
renderHints RenderHints — Override Skeleton shape and size hints.
respectMotionPreference boolean false When true, honor reduced motion and show the final number immediately.
font string — Digit font; inherits the container font when omitted.
size string | number — Number font size; number is converted to px, and the string can use SnowUI token or CSS value
weight string | number — Digit font weight; inherits the container weight when omitted.
lineHeight string | number — Root line height; the internal digit wheel retains its own 1em clipping window.
color SnowUIColor | string — The final text color inherits the container when it is not set.
align TextMotionAlign — Internal alignment of numbers
motionColor TextMotionColor — Temporary colors resolve across all target characters from left to right. chromatic() spans the full spectrum across retained digits, separators, and formatted currency symbols; it does not affect children.
children Snippet — Additional content on the left or right of the number

See the base component documentation for inherited capabilities not redeclared here. This table lists only named public Props declared by this component.

Usage boundaries and details

Overview and selection boundaries

NumberFlow suits continuous values such as counters, currency, metrics, and clocks. It splits formatted output with Intl.NumberFormat, keeps signs, grouping separators, and decimals, and rolls each digit. Use Text for static numbers; use NumericText, SlotText, or FlowText for character-level rearrangement or other text motion.

Import

import { NumberFlow } from "@snowui-design-system/components";

Examples

<NumberFlow    value={12840}    locales="en-US"    format={{ maximumFractionDigits: 0 }}    rollDirection="normal"/>

With a prefix, the numerical position is determined by numberPosition:

<NumberFlow value={99.5} numberPosition="right">    <Text>$</Text></NumberFlow>

Accessibility and composition boundaries

  • The final formatted text remains in the DOM. NumberFlow does not supply an accessible name that explains what the business metric means.

  • With respectMotionPreference={true}, reduced motion skips rolling, displacement, and delay and shows the final value immediately.

  • Browsers without CSS custom property registration fall back to number updates without continuous wheel interpolation; the text and formatting remain usable.

  • children only expresses additional content; numerical splitting, trend, roller track and width measurement are owned by NumberFlow.

NumberFlow style overlay

Read the full LICENSE first; reuse that review for the same task, version, and scope.

First use public component Props to match the desired appearance, preserving the existing look where possible. If changes are necessary, follow the style selection and override order: use your own class (including Tailwind already in the project) or an instance style. The names below are public overrides actually consumed by source; check their scope and do not modify private DOM. Choose the correct SnowUI token family. External apps need not install SnowUI website utilities.

This component source does not directly consume a registered component-specific override. Style composed children through public parts or an explicit child; do not guess variable names.

Design Guide · Token · Combination boundary

NumberFlow type and status

Required attribute: value.

Bindable Props: this component declares no named two-way binding; handle state updates through public callbacks or its host.

Inheritance: Omit<FrameProps, "children">. Consult the base class public documentation; fields excluded by Omit cannot be passed through unchanged.

Share Frame API · Return API

The following type declarations are actually referenced by public Props and come from source. A Svelte Snippet denotes a content fragment; ComponentProps denotes the Props of the corresponding component.

TrendResolver

Source: components/src/components/NumberFlow.svelte

type TrendResolver = TextMotionTrend;

TextMotionTrend

Source: components/src/lib/text-motion/types.ts

export type TextMotionTrend = -1 | 0 | 1;

TextMotionRole

Source: components/src/lib/text-motion/types.ts

export type TextMotionRole = "auto" | "text" | "number" | "timer" | "countdown";

NumberFlowTransition

Source: components/src/components/NumberFlow.svelte

interface NumberFlowTransition {        duration?: number;    }

RollDirection

Source: components/src/components/NumberFlow.svelte

type RollDirection = "normal" | "reverse";

RenderHints

Source: components/src/logic/frame-types.ts

export interface RenderHints {    variant?: SkeletonRenderVariant;    width?: string | number;    height?: string | number;    radius?: string | number;    rows?: number;}

SkeletonRenderVariant

Source: components/src/logic/frame-types.ts

export type SkeletonRenderVariant = "line" | "circle" | "rect";

SnowUIColor

Source: components/src/lib/color.ts

export type SnowUIColor = keyof typeof SNOWUI_COLOR_TOKENS;

TextMotionAlign

Source: components/src/lib/text-motion/types.ts

export type TextMotionAlign = "left" | "center" | "right" | "justify";

TextMotionColor

Source: components/src/lib/text-motion/types.ts

export type TextMotionColor = SnowUIColor | string | TextMotionColorResolver;

TextMotionColorResolver

Source: components/src/lib/text-motion/types.ts

export type TextMotionColorResolver = (index: number, total: number) => string;