api

This page lists everything you can import from the ascii.rest npm package, grouped by import path. Each entry gives its signature, one line on what it does, and the page that shows it in use.

A few words come up everywhere:

• A piece is one animation, like donut: a module with meta and a default function.
• A frame is the picture at one moment, as a string of text.
• A text piece is plain text in your page’s colour, drawn in a <pre>.
• A coloured piece (the scenes, logos, companies and distros) has colours of its own and is drawn on a <canvas>.

The shortest working example plays a piece in a <pre id="art">:

import { mount } from "ascii.rest";
import { donut } from "ascii.rest/pieces";

const stop = mount(document.querySelector<HTMLElement>("#art")!, donut);

stop() stops it. If you use an AI coding agent, this page is also in llms-full.txt, with every other docs page.

Pick an import path

Each import path is one part of the package. Import only the ones you use.

The package has no dependencies. React is an optional peer dependency, needed only for ascii.rest/react. Everything is typed.

ascii.rest

The main import: play a piece in an element, and find any piece by its name. Guide: typescript.

import { canvas, isPiece, load, mount, names } from "ascii.rest";

console.log(names.length); // 217

const name = new URLSearchParams(location.search).get("piece") ?? "donut";
if (isPiece(name)) {
  const el = document.createElement(canvas.has(name) ? "canvas" : "pre");
  document.body.append(el);
  mount(el, await load[name]());
}

mount()

mount(el: HTMLElement, piece: Piece | Piece["default"], options?: MountOptions): () => void

Plays a piece in el and returns a function that stops it. In a <pre>, any piece is text in the <pre>’s colour. On a <canvas>, a coloured piece is drawn in its own colours.

It plays only while el is on screen and the tab is visible. For a reader who prefers reduced motion it holds one still frame, unless you pass motion: true. piece can also be a bare function that returns a frame function. Guide: typescript.

load

const load: Record<PieceName, () => Promise<Piece>>

One function for each piece, by name. await load["night-coast"]() imports that piece’s module. A bundler puts each piece in its own file, so a page downloads only the pieces it plays.

names

const names: PieceName[]

The names of every piece, like "night-coast", in alphabetical order.

isPiece()

isPiece(name: string): name is PieceName

Returns true when a string is a piece’s name. In TypeScript it also narrows the string to PieceName. A piece’s name has dashes: isPiece("night-coast") is true and isPiece("nightCoast") is false.

canvas

const canvas: ReadonlySet<PieceName>

The names of the coloured pieces: the scenes, logos, companies and distros. Draw these on a <canvas> to see their colours.

Types from ascii.rest

ascii.rest/pieces

Every piece, as a named export. Its export is its name in camelCase: night-coast is nightCoast, and rule-30 is rule30. Every piece is in the list on the home page. Guide: your own pieces, which explains what a piece module holds.

import { bigText, donut } from "ascii.rest/pieces";

console.log(donut.meta.cols, donut.meta.rows); // 40 22
console.log(bigText.default({ text: "hi" })(0)); // the frame at 0 seconds

Each piece is a module with two exports:

One piece on its own

ascii.rest/pieces/<name> is one piece’s module, by the piece’s name, with dashes: ascii.rest/pieces/night-coast. The 113 pieces that take options also export a type for them: the piece’s name in PascalCase, plus Options. So big-text exports BigTextOptions, and spinners exports SpinnersOptions.

import * as spinners from "ascii.rest/pieces/spinners";
import type { BigTextOptions } from "ascii.rest/pieces/big-text";

const options: Partial<BigTextOptions> = { text: "hello" };
console.log(spinners.meta.options, options);

ascii.rest/banner

Turn any text into a piece in block letters with a drop shadow. The result plays anywhere a piece does: mount(), <Ascii>, svg() and play(). Guide: banners.

import { banner, drawable } from "ascii.rest/banner";

const hi = banner("hi", { shadow: "rounded" });
console.log(hi.default()(0));
console.log(drawable("héllo!")); // "hllo!": the font has no "é"

The first console.log prints:

▓▓╮   ▓▓╮ ▓▓╮
▓▓│   ▓▓│ ▓▓│
▓▓▓▓▓▓▓▓│ ▓▓│
▓▓╭───▓▓│ ▓▓│
▓▓│   ▓▓│ ▓▓│
╰─╯   ╰─╯ ╰─╯

banner()

banner(text: string, options?: BannerOptions): BannerPiece

Returns a piece that draws text in block letters. Every option is on banners.

It throws an error, with a message that says what to change, when:

• the font can draw none of text, apart from spaces;
• font or effect is a name it doesn’t know, or shadow is neither a name it knows nor 16 characters;
• a colour isn’t #rrggbb, or color is an empty list;
• fill isn’t exactly one character, or glint.chars isn’t one or two;
• gap, pad, pixel, size.cols or size.rows isn’t a whole number (gap and pad 0 or more, the others 1 or more);
• speed, max, glint.sweep, glint.every, glint.width or type.step isn’t above 0;
• glint.first or glint.slant isn’t a number.

drawable()

drawable(text: string, font?: FontName | Font): string

Returns the characters of text that the font can draw, in the case you gave them. banner() leaves the rest out. The font is "block" by default.

fonts

const fonts: { block: Font; slim: Font; tall: Font; bold: Font; round: Font; wide: Font; mixed: Font; italic: Font }

The eight built-in fonts. block, slim, wide and italic are five rows tall, round six, tall and bold seven, and mixed nine. mixed is cased, so it draws lower case too. Each one is shown on banners.

shadows

const shadows: Record<ShadowName, string>

The built-in shadow styles, double, single, heavy, rounded and ascii. Each is a string of 16 line-drawing characters: shadows.rounded is " │││─╯╮┤─╰╭├─┴┬┼".

Types from ascii.rest/banner

BannerPiece motion

A banner’s motion field says how it moves. svg() reads it to play exactly one loop. The terminal banner() reads it to play the first glint, or the typing, once.

import { banner } from "ascii.rest/banner";

banner("hi").motion; // { seconds: 3.2, from: 0, once: false, pass: [0.5, 2.9] }
banner("hi", { glint: { first: 0 } }).motion.from; // 2.8: at 0 the glint is in sight
banner("hi", { effect: "type" }).motion; // { seconds: 0.533..., from: 0, once: true }

ascii.rest/react

Two React components. Both are client components ("use client"), so they also work in the Next.js app router. Guides: react and next.js.

import { Ascii, Banner } from "ascii.rest/react";

export default function Page() {
  return (
    <>
      <Banner text="hello" color={["#f97316", "#f778ba"]} shadow="rounded" />
      <Ascii piece="donut" />
    </>
  );
}

Ascii

function Ascii(props: AsciiProps): JSX.Element

Plays a piece. It renders a <pre>, or a <canvas> for a coloured piece, with role="img". Guide: react.

Banner

function Banner(props: BannerProps): JSX.Element | null

Draws any text as a banner. Every option of banner() is a prop. If banner() throws, it renders nothing, and the console says why with console.warn: <Banner> could not draw: .... Guide: react.

Types from ascii.rest/react

AsciiProps and BannerProps are the props above. BannerOptions, MountOptions, Piece and PieceName are exported here too, so one import is enough.

ascii.rest/astro

Two Astro components, each the default export of its own path. For a text piece or banner, a still frame is rendered on the server, so the page shows it before any script runs. A coloured one keeps its space until its canvas draws. Guide: astro.

---
import Ascii from "ascii.rest/astro";
import Banner from "ascii.rest/astro/banner";
---

<Banner text="hello" shadow="rounded" />
<Ascii piece="night-coast" fps={12} />

Ascii

import Ascii from "ascii.rest/astro"

Plays a piece. It renders an <ascii-art> tag.

Banner

import Banner from "ascii.rest/astro/banner"

Draws any text as a banner. It renders an <ascii-banner> tag. If banner() throws, the error is thrown when the page renders.

This Banner has no fps prop.

ascii.rest/element

Importing this module defines two HTML tags, <ascii-art> and <ascii-banner>. On a server, where there is no DOM, it does nothing. The script https://ascii.rest/ascii.js is the same module, for a page with no build step. Guide: html.

import "ascii.rest/element";

const art = document.createElement("ascii-art"); // typed as AsciiArt
art.setAttribute("piece", "donut");
document.body.append(art);

AsciiArt

class AsciiArt extends HTMLElement

The <ascii-art> tag. Its attributes are piece, src, fps, options, label and mono. An unknown piece draws nothing and logs nothing. Guide: html.

AsciiBanner

class AsciiBanner extends HTMLElement

The <ascii-banner> tag. Its attributes are text, font, shadow, fill, effect, speed, color, shadow-color, pixel, gap, options, label and mono. An empty attribute counts as no attribute, except mono, which is on whenever it is there. If banner() throws, the tag draws nothing, and the console says why with console.warn: <ascii-banner> could not draw: .... Guide: html.

define()

define(tag?: string): void

Defines <ascii-art> under the name tag, and <ascii-banner>, if they aren’t defined yet. tag is "ascii-art" by default. Importing the module already calls define(), so call it yourself only to add another name, like define("my-art").

The module also tells TypeScript about both tags, so document.querySelector("ascii-art") has the type AsciiArt | null.

ascii.rest/svg

Turn any piece, or a banner, into an animated SVG string. An SVG plays where scripts can’t run, like a GitHub README or an <img>. It works in a browser, in Node, in a Worker or at build time. Guides: svg and github readme.

Most people only need svg() and bannerSvg(). The rest, from part() on, is for building your own SVG.

import { writeFileSync } from "node:fs";
import { bannerSvg, svg } from "ascii.rest/svg";
import { rust } from "ascii.rest/pieces";

writeFileSync("rust.svg", svg(rust));
writeFileSync("rust.dark.svg", svg(rust, { dark: true }));
writeFileSync("banner.svg", bannerSvg("my-project", { art: rust, color: "art", tagline: "fast, safe, fun" }));

svg()

svg(piece: Piece, options?: SvgOptions): string

Returns one loop of a piece as an animated SVG, on the piece’s meta.ground when it has one, as a scene does. It throws for an ink that isn’t #rrggbb, a scale that isn’t a number of 0 or more, or an fps outside 1 to 60. Guide: svg.

bannerSvg()

bannerSvg(text: string, options?: Omit<BannerOptions, "color"> & { color?: BannerSvgColor } & BannerSvgOptions): string

Returns a banner as an animated SVG, with an optional tagline under it, a piece beside or above it, and a background. Its options are every option of banner(), plus BannerSvgOptions. Its color also takes "art", the art’s own colour. Guide: svg.

It throws when banner() would, and also when:

• background or taglineColor isn’t #rrggbb, for either theme, whether or not it is used;
• taglineSize, spacing, padding, radius, artSize or scale isn’t a number of 0 or more;
• place isn’t "left", "right", "above" or "below", or align isn’t "start", "center" or "end";
• fps is outside 1 to 60;
• art is { svg } with an SVG that ascii.rest/svg didn’t write.

loopOf()

loopOf(piece: Piece, options?: Options): { every: number; from: number; once?: boolean }

The loop svg() plays: every, its length in seconds, and from, the time it starts. It is the first of these that applies:

1. a banner’s own motion (see BannerPiece motion);
2. every: 0, for a still piece, one whose meta.fps is 0;
3. the piece’s meta.loop;
4. for a logo, company or distro, the time between its glints or scans;
5. 4 seconds.

part()

part(loop: Loop & { cell?: number }, prefix?: string): Part

Samples a Loop into frames and returns them as a Part, with its CSS class names starting with prefix. It throws for an fps outside 1 to 60. Use it to put frames of your own in an SVG.

wrap()

wrap(part: Part, label: string, scale?: number): string

Puts a Part in a complete <svg>, titled label for screen readers. scale is the pixels per cell width, 10 by default.

namespaced()

namespaced(svg: string, prefix: string): Part | null

Turns an SVG that this module wrote back into a Part, with its class names, and its fade’s gradient, under prefix. Use it to put two in one SVG, or two inline in one HTML page. It returns null for any other SVG.

inkOf()

inkOf(part: Part): string | null

The colour that inks the most cells of a part’s first frame, such as a logo’s main colour. bannerSvg() uses it for color: "art".

darkColor()

darkColor(hex: string): boolean

Returns true when a #rrggbb colour is dark. bannerSvg() uses it to pick light or dark colours for a background.

MONO and FACES

const MONO: string and const FACES: string

MONO is the CSS rule that every part’s text rows share. part() leaves it out of a part’s css, and wrap() adds it. Add it to your SVG’s <style> yourself if you put parts in an SVG without wrap().

FACES is the list of monospace fonts that MONO names. Use it to set text of your own, such as a caption, in the same fonts at another size.

Types from ascii.rest/svg

ascii.rest/terminal

Play a piece, or print a banner, in a terminal: a splash screen for your CLI. It runs in Node and uses only Node’s built-in modules. Guide: terminal.

import { banner, play, still } from "ascii.rest/terminal";

await banner("my-cli", { color: ["#ff6a00", "#f778ba"], tagline: "v1.0" });
await play("donut", { seconds: 2 });
console.log(await still("donut"));

play()

play(piece: Piece | PieceName, options?: PlayOptions): Promise<Played>

Plays a piece in the middle of the terminal’s alternate screen. It resolves when it stops: after seconds, on any key, or on Ctrl+C. The terminal is put back however it stops. With no terminal to draw on, such as a pipe, it draws nothing and resolves at once. Guide: terminal.

banner()

banner(text: string, options?: PrintOptions): Promise<Bannered>

Prints a banner where the cursor is, moves it once, and leaves it in the scrollback. Piped, it prints at once with no colour. It keeps the banner a column narrower than the terminal. If even its narrowest letters don’t fit, it prints the text as one plain line. This is not the banner() from ascii.rest/banner: that one returns a piece, and this one prints. Guide: terminal.

still()

still(piece: Piece | PieceName, options?: { light?: boolean; options?: Options }): Promise<string>

Returns one frame as plain text, for a pipe or a log. It is the frame at meta.still, or the first. For a typed banner, that frame shows every letter.

Types from ascii.rest/terminal

Over HTTP

Some of the package is also served from ascii.rest itself, with nothing to install. Every path below is on https://ascii.rest.

Next

• typescript: mount(), frames and the types, with examples.
• banners: every option of banner().
• cli: the npx ascii.rest command.