TextMorph

Unlike TxTextTransformer's whole-string crossfade, the unit of motion here is the character segment. Surviving segments FLIP to their new position, arriving ones fade in from the nearest anchor, exiting ones leave the flow and fade out, and numbers additionally slide along the block axis by place value.

Basic Usage

TextMorph

Numeric Place-Value Roll

Digits are matched by place value rather than left to right: 1,204 → 1,318 rolls the hundreds and the tens and leaves the thousands alone, and the grouping comma travels with the magnitude, sliding a whole group along on 999,999 → 1,000,000.

Once the magnitude jumps by three places or more nothing carries across — at that point the digits overlap into a smear and a replacement is the honest reading.

Turn numbers off to fall back to the character-level morph.

Number place value

Spring Easing

spring takes a preset name or physical coefficients, and runs on the same spring compiler TxLiquid and TxSlider use, so the whole library shares one motion vocabulary. A spring supplies both the curve and the duration, so durationMs and easing are ignored while one is set.

Spring presets

API

TxTextMorph Props

TxTextMorph Events

Exactly one of animation-complete and animation-cancel runs per morph.

Behaviour Contract

• The whole value lives in one visually-hidden but readable [tx-morph-sr] node; every segment element is aria-hidden, so a screen reader announces the value once and never the fragments.
• Segments are created imperatively by the engine, so the component's styles are not scoped — containment comes from the tx-morph-* attribute names instead.
• Vue stops rendering the children after mount: the engine owns them. The first-paint plain text exists only so hydration matches.
• Under prefers-reduced-motion: reduce or disabled the value is written straight to textContent and the internal segment record is cleared, so re-enabling motion never FLIPs against elements that have already left the DOM.
• An update mid-morph reads the velocity the box is travelling at and carries it into the new curve, so a fast run of updates does not leave every curve stalled in its opening sliver.
• The root is white-space: nowrap. Line breaks come from \n in the value, which becomes a <br>; it does not soft-wrap and it does not ellipsise.
• cursorIndex is honoured only when the value holds exactly one number.

Best Practices

• Reach for it where the same quantity is changing — counters, totals, percentages. Place-value matching was written for exactly that.
• Pass cursorIndex for a number the user is typing, or inserting a digit before 20 reads as renumbering the whole column.
• Use TxTextTransformer with mode="fade" where the text has to soft-wrap or ellipsise; the engine cannot express either.
• Keep the number of high-frequency instances on one screen down: every character is an element carrying will-change.
• Let it size its own container — the engine animates width and height itself, so wrapping it in TxAutoSizer is redundant.

Source

• Component source: packages/tuffex/packages/components/src/text-morph/src/TxTextMorph.vue.
• Engine: packages/tuffex/packages/components/src/text-morph/src/engine/, ported from lochie/torph (MIT), with the spring layer replaced by TuffEx's own liquid/src/spring.ts.
• Types: packages/tuffex/packages/components/src/text-morph/src/types.ts exports TextMorphProps.
• Export alias: packages/tuffex/packages/components/src/text-morph/index.ts exports TextMorph, TxTextMorph, TextMorphProps, TxTextMorphInstance, plus the engine's TextMorphEngine / MorphController.
• Coverage: engine.test.ts and text-morph.test.ts under packages/tuffex/packages/components/src/text-morph/__tests__/ cover segmentation, diff pairing, place-value matching, the spring fusion and the reduced-motion fallback.