Skip to content

TextLoader

Copy page

TextLoader is Dotquilt’s loading placeholder for a number or a short label, such as a KPI. While it loads, its characters cross-fade through look-alikes in the shape of the answer. When the value arrives, the marks slide into the shapes of its real characters, then the value wipes in from left to right as they leave.

Preview
Loading

$48,120

TextLoader is its own loading region: set its state, and put the value in as its text. The mask is the shape of the answer, such as $00,000; without one, the placeholder takes the shape of the current text.

RevenueTotal.tsx
'use client';
import { TextLoader } from '@dotquilt/react';
import { useEffect, useState } from 'react';
async function fetchTotal(month: string, signal: AbortSignal): Promise<number> {
const response = await fetch(`/api/revenue/${month}/total`, { signal });
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const { total } = await response.json();
return total;
}
const money = new Intl.NumberFormat('en-US', {
style: 'currency',
currency: 'USD',
maximumFractionDigits: 0,
});
type Result =
| { status: 'loading' }
| { status: 'done'; total: number }
| { status: 'failed' };
export function RevenueTotal({ month }: { month: string }) {
const [result, setResult] = useState<Result>({ status: 'loading' });
useEffect(() => {
const request = new AbortController();
setResult({ status: 'loading' });
fetchTotal(month, request.signal)
.then((total) => setResult({ status: 'done', total }))
.catch(() => {
if (!request.signal.aborted) setResult({ status: 'failed' });
});
return () => request.abort();
}, [month]);
return (
<p className="kpi">
<TextLoader
aria-label="Revenue this month"
// The mask is the shape of the answer: the placeholder shows it in marks.
mask="$00,000"
state={result.status === 'loading' ? 'pending' : 'ready'}
cycle={month}
timing={result.status === 'failed' ? { duration: 0 } : undefined}
>
{result.status === 'done'
? money.format(result.total)
: result.status === 'failed'
? 'Unavailable'
: ''}
</TextLoader>
</p>
);
}
// Loads again whenever `month` changes.
export function Dashboard() {
return <RevenueTotal month="2026-11" />;
}
Attribute React Type Default Description
state state pending | refreshing | ready ready Whether the value is loading.
cycle cycle string Names one load, so a stale answer can’t settle a newer one.
delay delay number (ms) 0 Wait this long before showing the placeholder. A response inside it shows no placeholder and no handoff, so fast loads don’t flicker. A placeholder already on the page, such as server markup, is never hidden. Up to 10000.
min-display minDisplay number (ms) 0 Once a placeholder shows, keep it at least this long before handing over, so it never flashes. Up to 10000.
mask mask string the text The shape the placeholder shows.
mark mark dot | square | dash dot Squares make a clean pixel font. Dashes read as hatching here.
speed speed number 1 How fast the characters change.
pointer-response pointerResponse none | lift none lift lights the marks around the pointer while the placeholder shows, on devices with a fine pointer.
motion motion system | paused system system follows the visitor’s reduced-motion setting; paused stills the characters.
timing { duration?, easing? } The handoff’s length and curve. { duration: 0 } swaps at once.

Import alternatives from dotquilt/animations/text and pass them as animations.

Phase Default Also available
Idle scramble: characters cross-fade about every 280 ms scrambleCharacters: each character changes on its own clock; scrambleWords: one word changes at a time, in reading order; labelPulse: a calm highlight moves across the placeholder
Handoff morphWipe: the marks take the real characters’ shapes, then the value wipes in lock: characters lock left to right, each easing in over 300 ms; printText: the value prints in from the left as the characters lock; fade: the value fades in
Animation Options (default)
scramble, scrambleCharacters, scrambleWords changesPerSecond 0.5–4
labelPulse travelPxPerSecond 20–140 (70)
morphWipe travel 0.2–0.5 (0.34), wipeStart 0.3–0.6 (0.46), edge 4–80 px (36)
lock, printText staggerMs 0–60 (40), reelMs 0–100 (55), settleMs 40–400 (300), pop 0–0.3 (0)
fade duration ms (150)

The character effect draws Latin letters, digits and punctuation (printable ASCII) on a single line, up to 256 characters. Anything else still gets a placeholder: accented or non-Latin letters, right-to-left text, text that wraps, or longer text all show a plain field of marks in the text’s place, and the value fades in when it arrives. Wider character support may come in a later release.

While pending, the scrambled characters are hidden from assistive technology, so give the loader a label that says what is loading. When the value is ready, it is ordinary text.