# ascii.rest

> Animated ascii art for web pages, READMEs and terminals: 240 pieces, a banner for any text, an SVG writer, and a kit (ascii.rest/kit) for making your own pieces in a few lines, 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.
- To turn an image into ascii in code, use `fromImage()` from `ascii.rest/kit`: any image in a browser, PNG in Node. The page https://ascii.rest/make/ does the same with no code.
- To make a new piece, use `ascii.rest/kit` (version 0.4.0 or later). Start with a recipe, one call by name with options in words: looks such as `sea({ palette: "ocean" })` or `plasma().mask("HI")`, motions such as `spinning(torus())` or `floating(heart())`, widgets such as `clockFace()`, `gauge({ label: "cpu", value: "64%" })` or `progressBar()`. Only when no recipe fits, go down to `field()`, `scene()`, `particles()`, `picture()`, `fromSvg()`, effects such as `glint()`, layouts such as `grid()`, or `piece()` to draw on a grid.
- Everything the kit makes is a normal piece: pass it to `<Ascii piece={...}>`, `mount()`, `svg()` or `play()`. It also chains: `stars().behind(pulsing(heart())).named("love")`.
- Kit options take words: `speed: "slow"`, `amount: "subtle"`, `every: "rarely"`, a look's `scale: "large"`. Wherever it takes colours it takes a palette's name, such as `"ocean"`, `"fire"` or `"cola"`, as well as `#rrggbb`. A misspelt option or word throws with the ones it takes and a "did you mean".
- The kit's `barChart`, `gauge`, `sparkline`, `marquee`, `typewriter`, `heart` and others share names with library pieces. In one file, `import * as lib from "ascii.rest/pieces"` and use `lib.gauge` beside the kit's `gauge()`.
- In the kit, a frame should depend only on `t`. Use `random(seed)`, never `Math.random()`, and give `period` or `loop` so an SVG loops. `npx ascii.rest play file.ts --watch` plays a file's default export in the terminal as you edit it.

## start

- [introduction](https://ascii.rest/docs/): What ascii.rest is, the ways to use it, and what its 236 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.

## make your own

- [the kit](https://ascii.rest/docs/kit/): Make your own animated ascii art with ascii.rest/kit. Start with recipes, whole things in one line with no maths, then go deeper when you want to.
- [looks](https://ascii.rest/docs/kit-looks/): Moving pictures by name in one line, a sea, a plasma, aurora, flames, rain, a galaxy, with options in words and chaining like sentences.
- [motion](https://ascii.rest/docs/kit-motion/): Set anything moving in words, spinning, orbiting, bouncing, floating, pulsing, drifting, sliding in, with no angles and no maths.
- [widgets](https://ascii.rest/docs/kit-widgets/): Whole things in one call, a clock face, a progress bar, a spinner, a gauge, a chart, a card, a countdown, and placing things by words.
- [fields](https://ascii.rest/docs/kit-field/): field() makes ascii art from a formula of x, y and t, the way a shader draws a picture. One function, one piece.
- [drawing](https://ascii.rest/docs/kit-draw/): Draw on a piece's grid with text, lines, boxes, circles, polygons, stamps, braille plots and pixel art, with no maths.
- [maths](https://ascii.rest/docs/kit-math/): Noise, seeded randomness, easing, tweens, loops and a 3D camera, so a piece never writes its own.
- [3d scenes](https://ascii.rest/docs/kit-shapes3d/): scene() draws lit, spinning 3D shapes as ascii, from a donut, a planet with a moon and a cube to meshes and surfaces of your own.
- [particles](https://ascii.rest/docs/kit-particles/): particles() makes snow, rain, sparks, fireworks and systems of your own, said in words and plain numbers, looping exactly.
- [effects](https://ascii.rest/docs/kit-fx/): Effects that take any piece, banner or text and return a new piece, from a glint and a typing to a glitch, a wave, a rainbow and effects of your own.
- [layouts](https://ascii.rest/docs/kit-compose/): Pieces made of other pieces, side by side, in a grid with borders, layered over each other, played in turn, cropped, scaled and retimed.
- [images](https://ascii.rest/docs/kit-image/): fromImage() turns any image, a logo or a photo, into an ascii piece in code, in the browser or in Node, with the same drawing as the make page.
- [materials](https://ascii.rest/docs/kit-materials/): Build a picture by saying what is in it, a glass with water inside, a candle with a flame, a house with smoke from its chimney. No coordinates, no maths.
- [svg drawings](https://ascii.rest/docs/kit-vector/): fromSvg() turns any SVG, from Figma, Illustrator or an icon set, into an ascii piece, and brings its parts to life by name.

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