quanhoangindex/ascii-reveal

Contribute to quanhoangindex/ascii-reveal development by creating an account on GitHub.

Summary

ascii-reveal is a TypeScript React package that reveals text, images, and complete interface regions through an animated ASCII character grid. It also provides server-rendered loading skeletons, loading mascots, and a browser-only API, while keeping the real content in the DOM for screen readers.

What it is useful for

The library is useful when an interface needs a coordinated reveal rather than a separate animation for every element. Wrapping a subtree applies the effect to its text nodes, <img>, <canvas>, and <video> elements, while data-ascii="skip" can exclude controls that must remain usable.

It also supports practical loading flows. Set loading to scramble existing content out, show a shimmer or ASCII mascot, and decode the replacement content when loading finishes. For example, a metrics row can animate only the element matching [data-value], while a profile card can use AsciiSkeleton before its data arrives.

Accessibility behavior is built into the design: the underlying text remains available to screen readers, and prefers-reduced-motion replaces the reveal with a short fade. Server-rendered content is not hidden during hydration unless revealOnHydrate is explicitly enabled.

How engineers can use it

Install the package with React 17 or newer:

npm i ascii-reveal

The README also documents installing directly from GitHub:

npm i github:quanhoangindex/ascii-reveal

A basic reveal wraps the content that should animate:

import { AsciiReveal } from 'ascii-reveal';

<AsciiReveal preset="decode">
  <article className="card" data-ascii="surface">
    <img src="/cover.jpg" alt="" />
    <h2>Hello world</h2>
  </article>
</AsciiReveal>

For asynchronous data, pair the reveal with the skeleton component:

<AsciiReveal loading={!data}>
  {data ? <Profile data={data} /> : <AsciiSkeleton lines={3} />}
</AsciiReveal>

Engineers can select dither, scan, braille, or terminal skeleton variants, disable animation for long lists, and use animate={false} to avoid the shimmer. A non-React API is also available through ascii-reveal/core.

There are documented constraints: cross-origin images without CORS headers cannot be sampled and use a neutral glyph texture instead. If the wrapper changes size during a reveal, the animation finishes immediately; late-loading fonts should be awaited with document.fonts.ready. The README notes that the normal decode adds roughly 350–400 milliseconds before data becomes readable.