Pricing

NumericText handbook

v1.7.2 · @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 the parts of text or numbers that change while preserving unchanged content, suitable for short status, values, and time displays.

When to use it

Use it for number transitions. Use FlowText or SlotText for replacing whole text; configure appearance and formatting through public APIs.

  • Update the number with value; control formatting with locales and format. Set animated={false} to show the result immediately.

  • Reduced-motion preferences are honored by default. direction and trend control transition direction; use the system typography and color Props.

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 { NumericText, chromatic } from '@snowui-design-system/components';	const headlines = ['Build with SnowUI', 'Ship components', 'Write better docs'];	let headlineIndex = $state(0);</script> <div style="display: flex; flex-direction: column; align-items: center; gap: var(--gap-4);">	<NumericText value={headlines[headlineIndex]} motionRole="text" motionColor={chromatic()} size="--text-32" lineHeight="--leading-32" weight={600} />	<Button onclick={() => headlineIndex = (headlineIndex + 1) % headlines.length}>Next headline</Button></div>

API

Keyword Type Default Description
value NumericTextValue "" Displayed content
locales string "en-US" Locale for number formatting
format Intl.NumberFormatOptions — Number formatting options
animated boolean true Whether to animate content changes
trend NumericTextTrend 0 Decreasing, automatic, or increasing trend
direction NumericTextDirection "normal" Semantic direction. normal uses the shared trend; reverse reverses the direction for text, numbers, timers, and countdowns.
motionRole TextMotionRole "auto" Content semantics. text explicitly disables number inference; other values designate ordinary numbers, timers, or countdowns.
transition Partial<TextMotionTransition> — Motion timing entry matching numeric-text-main. Demo Slow Mode uses { duration: 550, easing: reference } by default.
respectMotionPreference boolean true Matches numeric-text-main; honors the system reduced-motion setting by default.
font string — Font family
size string | number — Font size
weight string | number — Font weight
lineHeight string | number — Line height
color SnowUIColor | string — Final text color
align TextMotionAlign — Alignment; inherits from the parent by default
motionColor TextMotionColor — Temporary color as target characters settle from left to right. Colors stay unchanged by default; supports a per-character chromatic() gradient.

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

Keyword

All six typography defaults inherit from the parent. SnowUI Tokens and PascalCase semantic colors such as color="Primary" are supported.

Numbers and time text use the shared trend protocol. Ordinary numbers compare actual result values; a negative sign does not change increase/decrease semantics. Multiplication and division use the larger or smaller result, not the operator, to choose Up or Down. Complete time strings use circular base-60 differences for mm:ss or HH:mm:ss. A single 00..59 segment also uses base-60 units when motionRole="timer" or "countdown". An increasing timer uses Up; a decreasing countdown uses Down. trend={1|-1} explicitly overrides automatic inference. direction="reverse" flips the final trend. motionRole="text" uses default trend 1 when no trend can be inferred, so reverse also affects plain text.

<NumericText    value={12840}    format={{ style: "currency", currency: "USD" }}    size="--text-24"    weight={600}    color="Primary"    motionColor="Indigo"/>

NumericText style overrides

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 · Tokens · Composition boundaries

NumericText types and states

Required Props: no named required Props.

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.

Shared Frame API · Back to 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.

NumericTextValue

Source: components/src/components/NumericText.svelte

export type NumericTextValue = string | number;

NumericTextTrend

Source: components/src/components/NumericText.svelte

export type NumericTextTrend = TextMotionTrend;

TextMotionTrend

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

export type TextMotionTrend = -1 | 0 | 1;

NumericTextDirection

Source: components/src/components/NumericText.svelte

export type NumericTextDirection = "normal" | "reverse";

TextMotionRole

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

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

TextMotionTransition

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

export interface TextMotionTransition {    duration: number;    easing: string;    layoutDuration?: number;}

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;