README проекта с github.com/quanhoangindex/ascii-reveal. Одним файлом markdown: README.md.
Recorded from the real component: <AsciiSkeleton> while loading, then <AsciiReveal> decodes the data in. Try the live demo →
<AsciiReveal loading={!data}>
{data ? <Profile data={data} /> : <AsciiSkeleton lines={3} />}
</AsciiReveal>
A loading effect for React. Text, images and whole cards decode into place through a character grid, in one wave across the page.
<img>, <canvas> and <video> inside it takes part.loading and the content scrambles out, a glyph shimmer runs where the data will land, then the new data decodes in.prefers-reduced-motion turns the reveal into a short fade.<AsciiSkeleton> is plain HTML and CSS: it paints on the first frame, renders on the server and needs no JavaScript. Data becomes readable about 400 ms after it arrives.From npm:
npm i ascii-reveal
Straight from GitHub (no npm publish needed):
npm i github:quanhoangindex/ascii-reveal
React 17 or newer is a peer dependency. The built files in dist/ are committed, so the GitHub install works without a build step.
import { AsciiReveal } from 'ascii-reveal';
export function Page() {
return (
<AsciiReveal preset="decode">
<article className="card" data-ascii="surface">
<img src="/cover.jpg" alt="" />
<h2>Hello world</h2>
<button data-ascii="fade">Read more</button>
</article>
</AsciiReveal>
);
}
The content reveals when the component mounts.
const { data, isLoading } = useQuery(...);
<AsciiReveal loading={isLoading} selector="[data-value]" revealOnMount={false}>
<dd data-value>{data?.latency ?? '—'}</dd>
</AsciiReveal>
When loading turns true, the matching content scrambles out and a shimmer runs in its place. When it turns false, the new content decodes in.
Skeletons exist to paint instantly while data loads. AsciiSkeleton does exactly that, in ASCII. There are two ways to use it (live demo):
1. Skeleton only. A drop-in replacement for a gray skeleton. Content appears as normal when it arrives.
import { AsciiSkeleton } from 'ascii-reveal';
{data ? <Profile data={data} /> : <AsciiSkeleton lines={3} />}
2. Skeleton + reveal. The skeleton paints first; when the data arrives, the real content decodes in (about 400 ms).
import { AsciiReveal, AsciiSkeleton } from 'ascii-reveal';
<AsciiReveal loading={!data}>
{data ? <Profile data={data} /> : <AsciiSkeleton lines={3} />}
</AsciiReveal>
The reveal never animates the skeleton itself. It leaves it alone while loading, and decodes the content that replaces it.
lines and widths shape a paragraph; rows, width, height and circle make a block for an image or avatar.Pick a style with variant:
variant |
Look |
|---|---|
dither (default) |
Shaded blocks ░▒▓█ that read as soft bars, with a darker dither band scanning across. |
scan |
Faint dots with a band of dense, scrambling glyphs. Matches the decode preset. |
braille |
Fine braille dot texture; the band fills the dots in. |
terminal |
Faint 0s and 1s, lit up in --ascii-accent as the band passes. |
<AsciiSkeleton variant="braille" lines={3} />
<AsciiSkeleton variant="dither" rows={6} width={64} height={64} circle />
<AsciiSkeleton animate={false} lines={2} /> {/* still pattern: cheapest, for long lists */}
Without React: el.innerHTML = asciiSkeletonHTML({ lines: 3 }), then animateSkeletons(el), both from ascii-reveal/core.
A skeleton only does its job if it shows up as fast as a gray box and never delays the data, so we measured it against one. Pre-rendered pages, no JavaScript needed to paint, Chromium on a machine without a GPU (so all drawing is done in software, the worst case), median of 7–11 runs:
| 12 cards, normal CPU | Gray skeleton | AsciiSkeleton | AsciiSkeleton animate={false} |
|---|---|---|---|
| First paint | 48 ms | 44 ms | 36 ms |
| Style + layout at load | 2 ms | 9 ms | 5 ms |
| Browser CPU while waiting | 15% | 21% | 0% |
| HTML (gzipped) | 0.5 KB | 3.2 KB | 3 KB |
How it stays cheap:
animate={false} skips the shimmer entirely.AsciiSkeleton never delays your data: content swaps in the moment it arrives. Only the optional AsciiReveal decode adds time (~350–400 ms after the data lands).SKELETON_CSS to your page once and use asciiSkeletonHTML({ css: false }) if that matters to you.el.innerHTML = asciiSkeletonHTML({ lines: 3 }), then animateSkeletons(el) to start the shimmer.Run it yourself: node scripts/skeleton-bench/build.cjs && node scripts/skeleton-bench/bench.cjs.
Content that arrives in server-rendered HTML is never hidden on hydration: it's already readable, so hiding it to animate it would make the page slower. Set revealOnHydrate if you want the effect anyway. Client-side navigations and loading transitions animate as usual.
Swap the shimmer for an animated ASCII mascot while data loads. It dissolves as the new content decodes in.
<AsciiReveal loading={isLoading} mascot="spider"> {/* spider | ghost | pumpkin | bat */}
<Stats data={data} />
</AsciiReveal>
<AsciiReveal loading={isLoading} mascot="/logo.svg">…</AsciiReveal> {/* your own SVG */}
Pass an SVG URL, SVG markup, or a draw function (ctx, w, h, t, color) => void for full control. Set --ascii-mascot to change the color of the line-art mascots.
const ref = useRef<AsciiRevealHandle>(null);
<AsciiReveal ref={ref}>…</AsciiReveal>
// replay one card from where it was clicked
ref.current?.reveal({ within: cardElement, origin: { x: e.clientX, y: e.clientY } });
ref.current?.hide();
| Prop | Type | Default | What it does |
|---|---|---|---|
preset |
'decode' | 'dither' | 'terminal' | 'blueprint' | Preset |
'decode' |
Glyph set, timing and image style. |
duration |
'fast' | 'cinematic' |
'fast' |
fast makes data readable in ~400 ms. cinematic is the slower, showier wave for hero sections. |
speed |
number |
1 |
Playback speed multiplier on top of duration. |
origin |
'center' | 'top-left' | 'pointer' | { x, y } |
'center' |
Where the wave starts. { x, y } is in viewport pixels. |
selector |
string |
– | Only animate content inside elements matching this selector. |
revealOnMount |
boolean |
true |
Reveal when the component mounts. |
loading |
boolean |
– | Scramble out and shimmer while true; decode in when it turns false. |
shimmer |
boolean |
true |
Show the glyph shimmer while loading. |
lazy |
boolean |
true |
Sections below the fold decode as they scroll into view instead of all at once. |
revealOnHydrate |
boolean |
false |
Also animate content that was server-rendered. |
fallback |
boolean |
true |
If frames take too long, finish the animation and use a short fade for the next 10 s. |
mascot |
'spider' | 'ghost' | 'pumpkin' | 'bat' | string | MascotDraw |
– | Animated ASCII mascot instead of the shimmer while loading. |
onRevealComplete |
() => void |
– | Called when a reveal finishes. |
as |
ElementType |
'div' |
Element used for the wrapper. |
All other props pass through to the wrapper element.
| Attribute | Effect |
|---|---|
data-ascii="surface" |
Cards and panels. A dot field and corner frame appear first, then the surface fades in. |
data-ascii="fade" |
Buttons, chips, badges. Fades in on the wave. |
data-ascii="media" |
Treat any element as media (rendered as a glyph texture). |
data-ascii="skip" |
Leave this subtree alone, for example a toolbar that must stay usable. |
data-ascii-digits |
Scramble only through digits (applied automatically to numeric text). |
The effect reads these CSS custom properties from the wrapper:
.my-app {
--ascii-accent: #5b8cff; /* cursor and blueprint glyphs */
--ascii-skeleton: #888; /* AsciiSkeleton glyph color (defaults to the text color) */
--ascii-flash: #5b8cff; /* optional: brief color as each character lands */
--ascii-glyph: #888; /* scramble glyph color (defaults to the text's own color at 50%) */
--ascii-font: "Geist Mono", ui-monospace, monospace;
--ascii-surface: #0b0b0d; /* color behind transparent images, if detection is wrong */
}
import { createAsciiReveal } from 'ascii-reveal/core';
const reveal = createAsciiReveal(document.querySelector('#app')!, { preset: 'dither' });
reveal.reveal();
// later
await reveal.hide();
reveal.shimmer(true);
Make your own by passing an object with the Preset shape (ramp, scramble, mode, color, cells, tick).
Measured on the demo page with Playwright and Chromium, CPU throttled 4×, on a machine with no GPU (so every frame is drawn in software, which caps even the idle page at ~19 fps). Run it yourself with scripts/bench.cjs (instructions at the top of the file).
| v0.2 | v0.3 | |
|---|---|---|
| Frame rate during Replay (page idle rate in brackets) | 8.4 fps (12.5) | 16.6 fps (19) |
| 95th percentile frame | 372 ms | 133 ms |
| Longest main-thread task | 297 ms | 174 ms |
| Data readable after it arrives | ~920 ms | ~350 ms |
Without throttling, v0.3 Replay runs at the page's idle frame rate and the longest task drops from 68 ms to under 20 ms. Note that v0.3's demo also replays only the card grid rather than the whole page.
What changed:
"use client".document.fonts.ready.currentColor stay visible while text is hidden. Emoji and combined characters are split correctly, and glyphs are clipped to scrolling containers.asciireveal event (detail: { active }) bubbles from the wrapper when animation starts and stops, if you want to pause your own effects meanwhile.npm install
npm run build # builds dist/
npm test # browser smoke test (npx playwright install chromium first)
npm run demo # runs the demo site (cd demo && npm install first)
See CHANGELOG.md for what changed between versions.
MIT