Description:
ascii-reveal is a React animation library that reveals text, images, and cards through an ASCII character grid.
It keeps content in the DOM and draws the scrambling effect above it, with a loading prop for asynchronous updates and a companion skeleton component.
Preview
Install
Use React and React DOM 17 or newer:
npm install ascii-revealAdd a reveal on mount
Wrap the content that should animate. Mark controls with data-ascii="fade" and card backgrounds with data-ascii="surface":
import { AsciiReveal } from 'ascii-reveal';
export function ArticleCard() {
return (
<AsciiReveal preset="decode">
<article data-ascii="surface">
<h2>Release notes</h2>
<p>The latest changes to your workspace.</p>
<a href="/releases" data-ascii="fade">View releases</a>
</article>
</AsciiReveal>
);
}Reveal loaded content
Set loading while a request is pending. During refreshes, content scrambles out and a shimmer occupies its place. When loading ends, replacement content decodes in. Skeletons remain outside the reveal animation.
Choose skeleton dimensions that match the expected content area:
import { AsciiReveal, AsciiSkeleton } from 'ascii-reveal';
type Profile = { name: string; role: string };
export function ProfileCard({ data, isLoading }: {
data: Profile | null;
isLoading: boolean;
}) {
return (
<AsciiReveal loading={isLoading} revealOnMount={false}>
{data ? (
<article>
<h2>{data.name}</h2>
<p>{data.role}</p>
</article>
) : (
<AsciiSkeleton variant="braille" lines={3} />
)}
</AsciiReveal>
);
}AsciiReveal props
| Prop | Default | Behavior |
|---|---|---|
preset | decode | decode, dither, terminal, blueprint, or a custom preset object |
duration | fast | fast or the longer cinematic treatment |
speed | 1 | Playback multiplier |
loading | Unset | Scrambles out while true, then reveals content when false |
shimmer | true | Glyph shimmer while loading |
mascot | Unset | Built-in mascot name, SVG URL or markup, or canvas draw callback |
origin | center | center, top-left, pointer, or viewport { x, y } coordinates |
selector | Unset | Limits animation to descendants that match a selector |
revealOnMount | true | Starts a reveal after mounting |
lazy | true | Reveals lower sections as they enter view |
revealOnHydrate | false | Opts server-rendered content into hydration animation |
fallback | true | Changes later reveals to a fade after slow frames |
onRevealComplete | Unset | Callback after a mount reveal or a loading reveal finishes |
as | div | Wrapper element type |
children | Unset | Content to animate |
Element attributes
| Attribute | Behavior |
|---|---|
data-ascii="surface" | Card or panel background treatment |
data-ascii="fade" | Fades the marked control on the reveal wave |
data-ascii="media" | Treats an element as media for glyph rendering |
data-ascii="skip" | Leaves the subtree outside the effect |
data-ascii-digits | Uses digits for scrambling |
AsciiSkeleton props
Use lines and widths for paragraphs. Set rows for an image or avatar block; it overrides lines. For long lists, pass animate={false} to skip the shimmer.
| Prop | Default | Purpose |
|---|---|---|
variant | dither | dither, scan, braille, or terminal |
lines | 3 | Number of text lines |
widths | Paragraph-shaped widths | Array of CSS lengths or pixel numbers |
rows | Unset | Glyph rows for a block placeholder |
width, height | Unset | Block dimensions as CSS lengths or pixel numbers |
circle | false | Round block placeholder |
seed | 1 | Seed for deterministic glyph patterns |
animate | true | Animated shimmer |
as | span | Wrapper element type |
Loading mascots and colors
For a mascot during loading, set mascot to spider, ghost, pumpkin, or bat. Custom SVG URLs, SVG markup, and canvas drawing functions are accepted too.
Pass className="profile-reveal" to AsciiReveal and set CSS custom properties on that wrapper:
.profile-reveal {
--ascii-accent: #5b8cff;
--ascii-skeleton: #888;
--ascii-glyph: #888;
--ascii-font: ui-monospace, monospace;
}
