# VS Modules / Typeshift

Typeshift.tsx is the React reference implementation, not a React requirement. Adapt its behavior into the project's existing framework (such as Svelte, Vue or plain JavaScript), using native state, lifecycle and cleanup. Reuse the browser Web Animations API and motion math; no animation library or stylesheet is required. Follow local naming conventions and inherit typography and color. The examples below use the reference React API; translate their syntax to the host framework.

Wrap changing text with <Typeshift value={value} />. Supply only the current string or number: the component remembers the previous value and automatically animates each update. From/To controls belong only to the playground. Optionally change replayKey to replay an identical value; ordinary rerenders do not retrigger motion. Optional duration sets milliseconds; countsDown overrides numeric direction. Without format props, plain decimal values get comma grouping automatically without rounding or dropping trailing decimal zeros; other text and zero-padded identifiers are preserved. The transition automatically rolls signed ASCII numbers with comma grouping and a decimal point. Latin text uses the same rolling animation and stagger per grapheme; combining marks stay attached. Contextual scripts and emoji roll as a complete shaped run. Decimal places retain their identity, unchanged numeric characters stay visible, while text transitions animate every grapheme. Animated characters roll up or down with a bounded left-to-right stagger and height-scaled blur. The shared curve is sampled from SwiftUI’s smooth spring; completed animations clear all temporary effects. This approximates SwiftUI contentTransition, not Apple's private renderer or arbitrary font-path morphing.

Optional tabular (default false) uses equal-width numeric digit slots and tabular figures for steadier numbers; text and punctuation keep natural widths. The playground exposes Tabular On/Off with Off selected by default; switching changes only spacing, preserving content without replaying. Both modes retain the same stagger and blur.

Optional format (Intl.NumberFormatOptions) supports currency, percentages and decimal precision: <Typeshift value={amount} format={{ style: 'currency', currency: 'EUR' }} />. Pass raw numbers or ASCII decimal strings. Explicit formatting uses native numeric rounding and consistent comma grouping; ordinary text is unchanged. Direction uses the underlying number, and digit identity follows formatted integer/fraction parts. disabled cancels motion and applies changes instantly; enabling it again does not replay previous updates. The playground exposes formatting and duration; disabled is an integration prop only. Integrations supply their own values and settings.

Keep the same text structure and typography during motion and at rest; replacing split graphemes with a plain text node can change kerning and ligatures. Measure animation geometry in local CSS pixels, not transformed screen pixels, and preserve the host’s width constraints. Avoid transitions on font, tracking or layout properties during the effect.

Use className or style for the host project's existing tokens. The component renders initial text on the server, animates subsequent changes, cancels previous animations on new updates or unmount, and immediately settles for reduced motion. Assistive technology receives one complete value, never individual rolling digits. Keep preview drafts temporary. Do not add autoplay, external font requests or per-frame framework state.

References: https://developer.apple.com/documentation/swiftui/view/contenttransition(_:) and https://developer.apple.com/videos/play/wwdc2023/10028/?time=360

Example: https://visual.systems/api/modules/typeshift/example.tsx