asciipaint/ docs

Getting startedInstall

Install

Add asciipaint with your package manager, or import it straight from a CDN. It has no runtime dependencies and needs WebGL2.

Package manager

Pick your manager; all four install the same package.

npm
npm i asciipaint
pnpm
pnpm add asciipaint
yarn
yarn add asciipaint
bun
bun add asciipaint

In Deno, import it from npm: import { asciipaint } from "npm:asciipaint".

From a CDN

No bundler? Import it as a module from esm.sh:

index.html
<script type="module">
  import { asciipaint } from "https://esm.sh/asciipaint";
</script>

cdn.jsdelivr.net/npm/asciipaint and unpkg.com/asciipaint serve it too.

Entry points

  • asciipaint: asciipaint() and autoRender(), for any image, video or canvas.
  • asciipaint/element: registers the <ascii-img> element when imported.
  • asciipaint/three: asciipaintThree(), for a three.js scene. three is an optional peer dependency (>=0.170), needed only here, plus @types/three in TypeScript.

WebGL2

asciipaint paints on the GPU and needs WebGL2, which every current evergreen browser has. Without it, asciipaint() throws asciipaint needs WebGL2, so wrap it if you want a fallback:

main.ts
import { asciipaint } from "asciipaint";

const canvas = document.querySelector("canvas")!;
try {
  const paint = asciipaint(canvas);
  // draw with paint…
} catch {
  canvas.hidden = true; // no WebGL2: show your plain picture instead
}

It runs in the browser only. Importing it on the server doesn’t crash and does nothing, so call it from client-side code, for example useEffect or an Astro island.

The font

The default font, Geist Mono at weight 600, is not bundled. Load it yourself, for example from Google Fonts, or the glyphs fall back to ui-monospace.