introduction

ascii.rest is a free, open-source library of animated ascii art: 217 small animations, called pieces, and block-letter banners for any text. You can play them on a web page, in a GitHub README or in a terminal.

ascii.rest is MIT licensed. You can use and change it in any project, free or paid.

Try it in one minute

Paste these lines into any HTML page. There is nothing to install.

<script type="module" src="https://ascii.rest/ascii.js"></script>

<ascii-art piece="donut"></ascii-art>
<ascii-banner text="hello" color="#f97316,#f778ba" shadow="rounded"></ascii-banner>

They draw this:

In a React or Next.js app, install the package:

npm install ascii.rest

Then use the components:

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

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

<Ascii> adds no CSS of its own. The style keeps the donut’s rows close together.

In a terminal, npx plays a piece without installing anything first. You need Node 18.3 or newer. Press any key to stop it.

npx ascii.rest donut

The quick start goes through each of these step by step.

Choose how to use it

Pick the row that fits your project. Each page has a full example.

Browse the pieces

There are 217 pieces in 15 categories. Each one has its own page at ascii.rest/<name>/, where it plays next to the code to use it. You can also see them all on one page.

The pieces come in two kinds, and each kind draws in its own way:

• A text piece is plain text in your page’s colour and font, drawn in a <pre>. 129 pieces are text pieces.
• A coloured piece has colours of its own and is drawn on a <canvas>. The 88 scenes, logos, companies and distros are coloured pieces.

A banner with no colour is drawn like a text piece. A banner with a colour is drawn like a coloured piece.

On a web page, a piece stops and starts on its own:

• It plays only while it is on screen and its tab is open.
• For readers who prefer reduced motion, it holds one still frame.

Besides the pieces, you can turn any text into a banner. Read banners, or make one in the banner maker.

Use it with an AI coding agent

Give your agent one of these plain-text files. Both are built from these docs pages.

• ascii.rest/llms.txt: an index, with one line and a link for each docs page. It includes the rules below.
• ascii.rest/llms-full.txt: every docs page in one file, to read all at once.

For example, tell it: “Read https://ascii.rest/llms-full.txt, then add the night-coast piece to my home page.”

Rules for AI coding agents

If your agent can’t read web pages, paste these rules into its prompt.

• The npm package is ascii.rest. It has no dependencies, and only ascii.rest/react needs React.
• A piece’s name has dashes, like night-coast. Its export from ascii.rest/pieces is in camelCase, like nightCoast.
• npx ascii.rest list prints every piece’s name.
• React: import { Ascii, Banner } from "ascii.rest/react". Both are client components already ("use client").
• In a React server component, pass a piece’s name, <Ascii piece="night-coast" />, not an imported module.
• Plain HTML: <script type="module" src="https://ascii.rest/ascii.js"></script>, then <ascii-art piece="donut"></ascii-art> or <ascii-banner text="hello"></ascii-banner>. Always write the closing tag.
• Astro: import Ascii from "ascii.rest/astro" and import Banner from "ascii.rest/astro/banner".
• Text pieces draw in a <pre>. Coloured pieces (scenes, logos, companies, distros) and banners with a colour draw on a <canvas>.
• React’s <Ascii> adds no CSS to a text piece’s <pre>: set line-height: 1.2; margin: 0 on it. The HTML tags and the Astro components set both for you.
• Size a text piece with font-size. Size a coloured piece with width (in React, in style, not a class), and never set its height.
• Colours are six-digit hex, like #f97316. #fff and orange don’t work.
• banner() throws on an option it can’t take. <Banner> and <ascii-banner> then draw nothing and console.warn why.
• The package has no function that turns an image into ascii. That is the page https://ascii.rest/make/, which runs in a browser.

Next

• quick start: from nothing to a piece on your page, one step at a time.
• examples: more examples to copy and paste.
• banners: any text in block letters, with every option.