ascii-img-react

ascii-img-react

ascii-img-react renders an image as ASCII art in React via an <AsciiImage> component. It matches each grid cell to the character whose shape fits best (6D shape vectors + nearest-neighbour), so edges stay crisp — unlike a brightness ramp. Pin a version: the package is young (0.1.0, MIT). Install + props live below; the full API is in references/component-api.md, the algorithm in references/technique.md.

Mental model

• Characters are matched by shape, not brightness. Six staggered sampling circles per cell form a 6D vector; the nearest character (Euclidean distance) wins. That is why diagonals and curves render as /, \, _ rather than a blocky ramp.
• The component samples the image on a hidden <canvas>, so the image must be same-origin or CORS-enabled (img.crossOrigin = "anonymous"). A cross-origin image without CORS headers renders blank.
• It outputs a <pre> of monospace text. Monospace fonts only — proportional fonts break the grid.
• The contrast and directionalContrast props are exactly the global and directional contrast-enhancement exponents from the technique (see references/technique.md).

Install

npm add [email protected]     # or: bun add / pnpm add / yarn add

Peer deps: React 18 or 19 (react, react-dom).

Usage

import { AsciiImage } from 'ascii-img-react';

export function Hero() {
  return (
    <AsciiImage
      src="/portrait.jpg"        // same-origin or CORS-enabled
      width={100}                 // output width in CHARACTERS
      color="#39ff14"             // green
      backgroundColor="#000"
      enableRipple={false}
    />
  );
}

width/height are in characters. cellWidth/cellHeight (px, default 6×12) set the sampling resolution. Defaults that matter: contrast={1.5}, directionalContrast={2}, enableDirectionalContrast, enableRipple, fontSize={10}, lineHeight={0.8}. Full prop table in references/component-api.md.