Text that diff-types between values with human-feeling jitter.
A primitive for any text that swaps from one value to another. Computes the minimal diff, backspaces the differing middle, pauses for a beat, then types in the new middle — with per-character jitter (and extra delay on harder-to-reach chars). Interruptible mid-animation, reduced-motion safe, and accepts a custom renderer for syntax tinting or word-by-word styling.
One install. The primitive exports nothing but the component and its prop types.
pnpm add @roy-ui/uiimport { TextMorph } from '@roy-ui/ui';Hand TextMorph any string. When the string changes, it diff-types from the old value to the new one — backspacing only the differing middle, pausing a beat, then typing in the replacement.
Toggle between two phrases. Watch the shared characters stay put while only the differing parts change.
const [tone, setTone] = useState<'casual' | 'formal'>('casual');
const lines = {
casual: "Hey, glad you're here.",
formal: "Welcome, we're delighted to see you.",
};
<TextMorph value={lines[tone]} />Numbers in a stat block — switching between time periods. Common digits get reused, new digits get typed in.
const [period, setPeriod] = useState<'today' | 'week' | 'month'>('today');
const counts = {
today: '1,287 signups',
week: '12,431 signups',
month: '50,892 signups',
};
<TextMorph value={counts[period]} />Symbol and amount change together. The 'mo' suffix stays put.
const [cur, setCur] = useState<'USD' | 'EUR' | 'GBP'>('USD');
const prices = {
USD: '$99/mo',
EUR: '€89/mo',
GBP: '£69/mo',
};
<TextMorph value={prices[cur]} />A real-world use case — package-manager switcher. This is the same primitive that powers the install pill in this site's hero.
const [pm, setPm] = useState('pnpm');
const cmds = {
pnpm: 'pnpm add @roy-ui/ui',
npm: 'npm install @roy-ui/ui',
yarn: 'yarn add @roy-ui/ui',
bun: 'bun add @roy-ui/ui',
};
<TextMorph value={cmds[pm]} />Pass a renderText prop to control how the in-progress string is rendered. The renderer fires on every keystroke with the current partial string — so syntax highlighting, gradient spans, or word-by-word styling stay correct mid-animation.
First word colored as the binary, second as the subcommand, rest as the package. The colors recompute on every frame, so partial states like 'n', 'np', 'npm' are tinted correctly.
<TextMorph
value={cmd}
renderText={(text) => {
const parts = text.split(' ');
return (
<>
{parts.map((part, i, arr) => {
const cls = i === 0 ? 'bin' : i === 1 ? 'sub' : 'pkg';
return (
<span key={i} className={cls}>
{part}{i < arr.length - 1 ? ' ' : ''}
</span>
);
})}
</>
);
}}
/>Things you get for free, things you can tune.
[30, 60] ms for typing, [18, 30] ms for backspace. No two delays match — it reads as a person typing./[\/{}\-_@]/ catches slashes, braces, hyphens, underscores, and at-signs — characters that take a real human a beat longer to reach. They get an extra [30, 65] ms delay.value prop mid-animation and the previous animation cancels cleanly — the new one starts from whatever character is on screen right now. No queued ghost typings.prefers-reduced-motion: reduce get an instant text swap. No animation, no jitter.Every native span attribute is forwarded — id, style, aria-*, data-*, ref.
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | — | The current text. Changing this triggers the diff-type animation. |
renderText | (current: string) => ReactNode | — | Optional renderer for the in-progress text. Fires every keystroke with the partial string. |
typeDelay | [min, max] | [30, 60] | Per-character typing delay range in ms. |
backspaceDelay | [min, max] | [18, 30] | Per-character backspace delay range in ms. |
hardChars | RegExp | /[\/{}\-_@]/ | Characters that get an additional delay (slower to reach on a keyboard). |
hardCharExtraDelay | [min, max] | [30, 65] | Extra delay range for hard chars in ms. |
pauseMs | number | 70 | Pause between the backspace phase and the typing phase. |
disabled | boolean | false | Skip animation entirely and swap text instantly. Also implicit when prefers-reduced-motion is set. |
...rest | HTMLAttributes<HTMLSpanElement> | — | All native span props (className, style, aria-*, ref). |