Images

ASCII Scroll Reveal

An image that resolves from coarse glyphs to the photo as it scrolls into view.

Field notes · 04

Pictures at low resolution

Squint at a photo and it falls apart into blocks of light and shadow. Set those blocks in type and you get something between a print and a puzzle.

Scroll down. The picture below starts as a handful of big glyphs and sharpens as it reaches the middle.

scroll ↓

Every step down in cell size quadruples the number of characters, so the image resolves quickly at first and then settles in the details: a ridge, a petal, a reflection.

Keep scrolling and it stays sharp. Scroll back up and it coarsens again, so the effect is tied to the position, not to a timer.

End of notes.

Controls

photo

from

reveal

charset

color

Installation

pnpm dlx shadcn@latest add @asciicn/ascii-scroll-reveal

Pulls in the engine at lib/ascii on first install. The @asciicn namespace needs one line in components.json, see Installation.

Manual installation

Install the engine first with npx shadcn@latest add @asciicn/ascii-core, or copy lib/ascii from the repository.

Copy this into components/ascii/ascii-scroll-reveal.tsx:

"use client"

import { useEffect, useEffectEvent, useRef, useState } from "react"

import { AsciiCanvas, type AsciiCanvasProps } from "@/lib/ascii"
import { cn } from "@/lib/utils"

export type AsciiScrollRevealProps = Omit<AsciiCanvasProps, "source" | "fontSize" | "onProgress"> & {
  src: string
  alt: string
  /** Cell size in CSS pixels as the image enters from below. */
  from?: number
  /** Cell size once the image reaches the middle of the scroll area. */
  to?: number
  /** "photo" cross-fades to the original over the last stretch, "ascii" stays glyphs. */
  reveal?: "photo" | "ascii"
  onProgress?: (progress: number) => void
}

function scrollParent(el: HTMLElement): HTMLElement | null {
  for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) {
    if (p.scrollHeight > p.clientHeight && /(auto|scroll|overlay)/.test(getComputedStyle(p).overflowY)) return p
  }
  return null
}

/** Coarse glyphs that resolve into the photo as the image scrolls toward the middle of its scroll area. */
export function AsciiScrollReveal({
  src,
  alt,
  from = 32,
  to = 6,
  reveal = "photo",
  onProgress,
  className,
  ...props
}: AsciiScrollRevealProps) {
  const [image, setImage] = useState<HTMLImageElement | null>(null)
  const [fontSize, setFontSize] = useState(from)
  const root = useRef<HTMLDivElement>(null)

  const apply = useEffectEvent((p: number) => {
    root.current!.style.setProperty("--reveal", String(p))
    // Geometric steps feel even, and whole pixels keep canvas redraws to a few dozen over the whole scroll.
    setFontSize(Math.round(from * Math.pow(to / from, p)))
    onProgress?.(p)
  })

  useEffect(() => {
    const img = new Image()
    img.crossOrigin = "anonymous"
    img.onload = () => setImage(img)
    img.src = src
    return () => {
      img.onload = null
    }
  }, [src])

  useEffect(() => {
    const el = root.current!
    const reduce = matchMedia("(prefers-reduced-motion: reduce)")
    const scroller = scrollParent(el)
    const target: HTMLElement | Window = scroller ?? window
    let raf = 0

    const measure = () => {
      raf = 0
      let p = 1
      if (!reduce.matches) {
        const r = el.getBoundingClientRect()
        const view = scroller ? scroller.getBoundingClientRect() : { top: 0, height: innerHeight }
        // 0 when the top edge enters from below, 1 once the centre reaches the middle of the view.
        p = (view.top + view.height - r.top) / (view.height / 2 + r.height / 2)
        p = Math.min(1, Math.max(0, p))
      }
      apply(p)
    }
    const schedule = () => {
      if (!raf) raf = requestAnimationFrame(measure)
    }
    const io = new IntersectionObserver(
      ([e]) => {
        if (e.isIntersecting) {
          target.addEventListener("scroll", schedule, { passive: true })
          window.addEventListener("resize", schedule)
        } else {
          target.removeEventListener("scroll", schedule)
          window.removeEventListener("resize", schedule)
        }
        schedule()
      },
      { root: scroller },
    )

    io.observe(el)
    reduce.addEventListener("change", schedule)
    measure()
    return () => {
      cancelAnimationFrame(raf)
      io.disconnect()
      reduce.removeEventListener("change", schedule)
      target.removeEventListener("scroll", schedule)
      window.removeEventListener("resize", schedule)
    }
  }, [from, to])

  return (
    <div
      ref={root}
      className={cn("relative w-full overflow-hidden", className)}
      style={{ aspectRatio: image ? `${image.naturalWidth} / ${image.naturalHeight}` : "1" }}
    >
      <AsciiCanvas source={image} fontSize={fontSize} aria-label={alt} className="absolute inset-0" {...props} />
      {reveal === "photo" && (
        // eslint-disable-next-line @next/next/no-img-element -- crossfade target must be the same file the canvas samples
        <img
          src={src}
          alt=""
          className="absolute inset-0 size-full object-cover"
          style={{ opacity: "clamp(0, (var(--reveal, 0) - 0.75) * 4, 1)" }}
        />
      )}
    </div>
  )
}

Usage

import { AsciiScrollReveal } from "@/components/ascii/ascii-scroll-reveal"

<AsciiScrollReveal
  src="/work/cover.jpg"
  alt="Project cover"
  from={32}
  to={6}
/>

Examples

Stay in glyphs

reveal="ascii" stops at the finest grid instead of fading to the photo. With braille and a palette it reads like a print.

scroll ↓

Props

Prop	Type	Default	Description
src	string	—	Image URL. Cross-origin images need CORS headers.
alt	string	—	Accessible label for the canvas.
from	number	32	Cell size in pixels as the image enters from below.
to	number	6	Cell size once the image's centre reaches the middle of the view.
reveal	"photo" \| "ascii"	"photo"	Photo cross-fades to the original over the last quarter. ASCII stays glyphs.
onProgress	(progress: number) => void	—	Scroll progress from 0 to 1, at most once per frame.

Engine props (inherited from AsciiCanvas)

Prop	Type	Default	Description
charset	CharsetName \| string	"standard"	Named ramp or your own string, empty to dense. "braille" packs 2×4 dots per cell, "quadrants" 2×2 blocks.
fontSize	number	12	Cell size in CSS pixels. Smaller means more detail.
dither	"none" \| "bayer" \| "floyd"	"none"	Quantisation. Floyd–Steinberg for photos, Bayer for a retro look.
color	"ink" \| "source" \| string[]	"ink"	Ink uses the CSS colour (theme with text-*). Source keeps pixel colours. An array maps tone onto gradient stops, e.g. palettes.thermal.
edges	number	0	Outline contours with \| / - \ where the tone gradient beats this strength. Try 0.3. Ramps only.
opacity	boolean	false	Fade each glyph by its tone.
brightness	number	0	Added after contrast, -1 to 1.
contrast	number	1	Multiplier around mid grey.
gamma	number	1	Tone curve exponent.
invert	boolean	false	Swap ink and blank.
animate	boolean	auto	On for fields, frames and video. Off under reduced motion, except video.
fps	number	30	Frame cap.
ref	Ref<AsciiHandle>	—	Exposes text(), svg(), png() and the canvas.

Notes

Scroll container. Progress follows the nearest ancestor that scrolls vertically, or the viewport when there is none. It reaches 1 when the image is centred and stays there as it scrolls out the top.
Accessibility. The canvas has role="img" and takes alt as its label. The fade-in photo is decorative (alt=""), so the label isn't read twice.
Motion. Under prefers-reduced-motion the image shows its final state straight away and ignores scrolling.
Performance. Scroll is read once per frame, and only while the image is on screen. The canvas redraws only when the cell size crosses a whole pixel; the photo fade is a CSS variable.

Installation

pnpm dlx shadcn@latest add @asciicn/ascii-scroll-reveal

Pulls in the engine at lib/ascii on first install. The @asciicn namespace needs one line in components.json, see Installation.

Manual installation

Install the engine first with npx shadcn@latest add @asciicn/ascii-core, or copy lib/ascii from the repository.

Copy this into components/ascii/ascii-scroll-reveal.tsx:

"use client"

import { useEffect, useEffectEvent, useRef, useState } from "react"

import { AsciiCanvas, type AsciiCanvasProps } from "@/lib/ascii"
import { cn } from "@/lib/utils"

export type AsciiScrollRevealProps = Omit<AsciiCanvasProps, "source" | "fontSize" | "onProgress"> & {
  src: string
  alt: string
  /** Cell size in CSS pixels as the image enters from below. */
  from?: number
  /** Cell size once the image reaches the middle of the scroll area. */
  to?: number
  /** "photo" cross-fades to the original over the last stretch, "ascii" stays glyphs. */
  reveal?: "photo" | "ascii"
  onProgress?: (progress: number) => void
}

function scrollParent(el: HTMLElement): HTMLElement | null {
  for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) {
    if (p.scrollHeight > p.clientHeight && /(auto|scroll|overlay)/.test(getComputedStyle(p).overflowY)) return p
  }
  return null
}

/** Coarse glyphs that resolve into the photo as the image scrolls toward the middle of its scroll area. */
export function AsciiScrollReveal({
  src,
  alt,
  from = 32,
  to = 6,
  reveal = "photo",
  onProgress,
  className,
  ...props
}: AsciiScrollRevealProps) {
  const [image, setImage] = useState<HTMLImageElement | null>(null)
  const [fontSize, setFontSize] = useState(from)
  const root = useRef<HTMLDivElement>(null)

  const apply = useEffectEvent((p: number) => {
    root.current!.style.setProperty("--reveal", String(p))
    // Geometric steps feel even, and whole pixels keep canvas redraws to a few dozen over the whole scroll.
    setFontSize(Math.round(from * Math.pow(to / from, p)))
    onProgress?.(p)
  })

  useEffect(() => {
    const img = new Image()
    img.crossOrigin = "anonymous"
    img.onload = () => setImage(img)
    img.src = src
    return () => {
      img.onload = null
    }
  }, [src])

  useEffect(() => {
    const el = root.current!
    const reduce = matchMedia("(prefers-reduced-motion: reduce)")
    const scroller = scrollParent(el)
    const target: HTMLElement | Window = scroller ?? window
    let raf = 0

    const measure = () => {
      raf = 0
      let p = 1
      if (!reduce.matches) {
        const r = el.getBoundingClientRect()
        const view = scroller ? scroller.getBoundingClientRect() : { top: 0, height: innerHeight }
        // 0 when the top edge enters from below, 1 once the centre reaches the middle of the view.
        p = (view.top + view.height - r.top) / (view.height / 2 + r.height / 2)
        p = Math.min(1, Math.max(0, p))
      }
      apply(p)
    }
    const schedule = () => {
      if (!raf) raf = requestAnimationFrame(measure)
    }
    const io = new IntersectionObserver(
      ([e]) => {
        if (e.isIntersecting) {
          target.addEventListener("scroll", schedule, { passive: true })
          window.addEventListener("resize", schedule)
        } else {
          target.removeEventListener("scroll", schedule)
          window.removeEventListener("resize", schedule)
        }
        schedule()
      },
      { root: scroller },
    )

    io.observe(el)
    reduce.addEventListener("change", schedule)
    measure()
    return () => {
      cancelAnimationFrame(raf)
      io.disconnect()
      reduce.removeEventListener("change", schedule)
      target.removeEventListener("scroll", schedule)
      window.removeEventListener("resize", schedule)
    }
  }, [from, to])

  return (
    <div
      ref={root}
      className={cn("relative w-full overflow-hidden", className)}
      style={{ aspectRatio: image ? `${image.naturalWidth} / ${image.naturalHeight}` : "1" }}
    >
      <AsciiCanvas source={image} fontSize={fontSize} aria-label={alt} className="absolute inset-0" {...props} />
      {reveal === "photo" && (
        // eslint-disable-next-line @next/next/no-img-element -- crossfade target must be the same file the canvas samples
        <img
          src={src}
          alt=""
          className="absolute inset-0 size-full object-cover"
          style={{ opacity: "clamp(0, (var(--reveal, 0) - 0.75) * 4, 1)" }}
        />
      )}
    </div>
  )
}

Props

Prop	Type	Default	Description
src	string	—	Image URL. Cross-origin images need CORS headers.
alt	string	—	Accessible label for the canvas.
from	number	32	Cell size in pixels as the image enters from below.
to	number	6	Cell size once the image's centre reaches the middle of the view.
reveal	"photo" \| "ascii"	"photo"	Photo cross-fades to the original over the last quarter. ASCII stays glyphs.
onProgress	(progress: number) => void	—	Scroll progress from 0 to 1, at most once per frame.

Engine props (inherited from AsciiCanvas)

Prop	Type	Default	Description
charset	CharsetName \| string	"standard"	Named ramp or your own string, empty to dense. "braille" packs 2×4 dots per cell, "quadrants" 2×2 blocks.
fontSize	number	12	Cell size in CSS pixels. Smaller means more detail.
dither	"none" \| "bayer" \| "floyd"	"none"	Quantisation. Floyd–Steinberg for photos, Bayer for a retro look.
color	"ink" \| "source" \| string[]	"ink"	Ink uses the CSS colour (theme with text-*). Source keeps pixel colours. An array maps tone onto gradient stops, e.g. palettes.thermal.
edges	number	0	Outline contours with \| / - \ where the tone gradient beats this strength. Try 0.3. Ramps only.
opacity	boolean	false	Fade each glyph by its tone.
brightness	number	0	Added after contrast, -1 to 1.
contrast	number	1	Multiplier around mid grey.
gamma	number	1	Tone curve exponent.
invert	boolean	false	Swap ink and blank.
animate	boolean	auto	On for fields, frames and video. Off under reduced motion, except video.
fps	number	30	Frame cap.
ref	Ref<AsciiHandle>	—	Exposes text(), svg(), png() and the canvas.

Notes

Scroll container. Progress follows the nearest ancestor that scrolls vertically, or the viewport when there is none. It reaches 1 when the image is centred and stays there as it scrolls out the top.

Accessibility. The canvas has role="img" and takes alt as its label. The fade-in photo is decorative (alt=""), so the label isn't read twice.

Motion. Under prefers-reduced-motion the image shows its final state straight away and ignores scrolling.

Performance. Scroll is read once per frame, and only while the image is on screen. The canvas redraws only when the cell size crosses a whole pixel; the photo fade is a CSS variable.