# ascii.rest

> Animated ascii art for web pages, READMEs and terminals: 217 pieces, a banner for any text and an SVG writer, in TypeScript with no dependencies. npm install ascii.rest, one script tag, or the source copied in through a shadcn registry.

## 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.

## start

- [introduction](https://ascii.rest/docs/): What ascii.rest is, five ways to use it, and what its 217 pieces are.
- [quick start](https://ascii.rest/docs/quickstart/): Get an animation on your page in under two minutes, with one script tag, with React or Next.js, or in your terminal.
- [install](https://ascii.rest/docs/install/): Add ascii.rest to your project from npm, with one script tag, or as source files you own.
- [examples](https://ascii.rest/docs/examples/): Recipes to copy and paste, one for each thing people build most, from a hero scene and a 404 page to a README banner and a CLI splash screen.

## use it in

- [react](https://ascii.rest/docs/react/): Play any piece, or draw any text as a banner, in a React or Next.js app.
- [next.js](https://ascii.rest/docs/nextjs/): Play pieces and banners on Next.js pages, with the app router or the pages router, and serve banners as SVG images.
- [astro](https://ascii.rest/docs/astro/): Add an animation or a text banner to an Astro page, with its first frame already in the HTML.
- [html](https://ascii.rest/docs/html/): Add animated ascii art and text banners to any web page with one script tag, no install and no build step.
- [typescript](https://ascii.rest/docs/typescript/): Play any piece on a web page with plain TypeScript and no framework, or draw its frames yourself.
- [your own copy](https://ascii.rest/docs/copy/): Copy the TypeScript of any piece, the banner or the React components into your project, so you own it and can change it.

## make

- [banners](https://ascii.rest/docs/banners/): Draw any text in big block letters, then change its font, shadow, colours, motion and size.
- [image to ascii](https://ascii.rest/docs/images/): Turn a logo or a photo into animated ascii in your browser, then put it on a web page, in a README, or in the library.
- [svg](https://ascii.rest/docs/svg/): Turn any piece, or a banner of your own text, into an animated SVG that plays without JavaScript.
- [github readme](https://ascii.rest/docs/readme/): Put a moving logo, or your name in big block letters, at the top of a GitHub README.
- [terminal](https://ascii.rest/docs/terminal/): Play any piece in your terminal, print your text as a banner, or add a splash screen to your own command-line tool.
- [your own pieces](https://ascii.rest/docs/pieces/): Write your own animation as a piece, then play it in React, on any web page, as an SVG or in a terminal.

## reference

- [api](https://ascii.rest/docs/api/): Every function, component and type the ascii.rest package exports, with its signature and the page that shows it in use.
- [cli](https://ascii.rest/docs/cli/): Every command and flag of npx ascii.rest, what each one prints, and the exit codes it returns.
- [questions](https://ascii.rest/docs/faq/): Short answers to the questions people ask most, each with a link to the page that has the details.

## more

- [every docs page in one file](https://ascii.rest/llms-full.txt): to read the whole of the docs at once
- [every piece](https://ascii.rest/#pieces): each with its own page, at https://ascii.rest/<name>/, and its source
- [registry index](https://ascii.rest/r/registry.json): every shadcn registry item
- [source](https://github.com/bas3line/ascii): MIT licensed