ascii-rest
Add animated ascii art with ascii.rest to web pages, GitHub READMEs and terminals. 242 ready pieces (scenes, spinners, charts, language, company and Linux distro logos, 3D shapes, weather, creatures), text in big block-letter banners, any image or logo turned to ascii, and a kit for making new ones. Use when the user wants ascii art, a retro or terminal look, a text animation or loader, an animated README banner or logo, a CLI splash screen, or names ascii.rest, in React, Next.js, Astro, Vue, Svelte, plain HTML, a README or a terminal.
How do I install this agent skill?
npx skills add https://github.com/bas3line/ascii --skill ascii-restIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides instructions and documentation for using the ascii.rest library to generate animated ASCII art. It identifies standard integration patterns for frameworks like React, Astro, and Next.js, as well as terminal usage. No malicious activity or security risks were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
ascii.rest
ascii.rest is an npm package, ascii.rest, with no dependencies: 242 animated pieces of ascii art, each one a small TypeScript module, plus banners (any text in block letters) and a kit to make more. Every piece plays only while it is on screen and holds one still frame for readers who prefer reduced motion, so it needs no extra code for either.
Work in this order
- Find where it goes. Read
package.jsonand the files around the spot the user means:next→ Next.js,react→ React,astro→ Astro,vue,svelteor no framework → the HTML tags.- A
README.mdon GitHub → an SVG, since GitHub runs no script. - A CLI in Node →
ascii.rest/terminal.
- Pick the piece. Search references/pieces.md by category and by what each one shows. Use a name exactly as it is listed there, or as
npx ascii.rest listprints it. Never make one up: an unknown name draws nothing. For a language, a company or a distro, look under logos, companies and distros first. When nothing fits, make one with the kit (below), or ask. - Add it the way the target needs (below), with the rules at the end.
- Check it. Run the project's dev server or build and look at the page. For a README, open the SVG's URL. For a terminal, run
npx ascii.rest <name> --seconds 3.
Put a piece on a page
Install it for React, Next.js, Astro or a bundler: npm install ascii.rest.
React and Next.js. <Ascii> is already a client component.
import { Ascii } from "ascii.rest/react";
import { donut } from "ascii.rest/pieces";
<Ascii piece={donut} />
In a server component, pass the name instead of a module: <Ascii piece="donut" />. With options: <Ascii piece={typewriter} options={{ phrases: ["hello"] }} />.
Astro. It renders the first frame on the server, so the page is whole before any script runs.
---
import Ascii from "ascii.rest/astro";
---
<Ascii piece="donut" />
Plain HTML, no build step. The script loads each piece from ascii.rest on demand.
<script type="module" src="https://ascii.rest/ascii.js"></script>
<ascii-art piece="donut"></ascii-art>
Vue, Svelte or anything else with a bundler. Import the tags once, in code that runs in the browser, then write them in templates as in HTML. Tell the framework that ascii-art and ascii-banner are custom elements (in Vue, compilerOptions.isCustomElement).
import "ascii.rest/element";
Any element, by hand. mount() plays a piece in a <pre> (text pieces) or a <canvas> (canvas pieces) and returns a function that stops it. Call it when the element goes away.
import { mount } from "ascii.rest";
import { donut } from "ascii.rest/pieces";
const stop = mount(document.querySelector<HTMLPreElement>("#art")!, donut);
Write text in block letters
import { Banner } from "ascii.rest/react"; // Astro: import Banner from "ascii.rest/astro/banner"
<Banner text="hello" />
<Banner text="hello" font="slim" shadow="rounded" effect="type" />
<Banner text="hello" color={["#f97316", "#f778ba"]} />
In HTML, font, shadow, fill, effect, speed, color (colours joined by commas), pixel and gap are attributes: <ascii-banner text="hello" font="slim" color="#f97316,#f778ba"></ascii-banner>. Every other option goes in the options attribute as JSON, or it is ignored: <ascii-banner text="hello" options='{"max":40,"pad":1}'></ascii-banner>. The options: font (block, slim, tall, bold, round, wide, mixed, italic), shadow (double, single, heavy, rounded, ascii, none), color (one #rrggbb or a list for a fade), effect (glint, type, still), speed, fill, pad, max. All of them, with what each takes: references/docs/banners.md. A banner draws only the characters its font has: letters, digits, spaces and . , ! ? ' : - + = / _.
Put one in a GitHub README
GitHub runs no script, so use the animated SVGs, a light and a dark one:
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://ascii.rest/svg/rust.dark.svg">
<img alt="rust" src="https://ascii.rest/svg/rust.svg" width="240">
</picture>
Only the logos, companies and distros have hosted SVGs: https://ascii.rest/svg/<name>.svg and .dark.svg. Any other piece has no URL and would be a broken image: make its SVG with svg() from ascii.rest/svg, write both files into the repo and point the README at them (references/docs/svg.md). A banner is https://ascii.rest/banner/<text>.svg and .dark.svg, with the text URL-encoded (a space is %20, a comma %2C), up to 20 characters. Its look goes in the query, the same on both URLs: ?color=f97316,f778ba&tagline=making%20things&art=rust&effect=type. Colours in a URL have no #. Every key: references/docs/readme.md. The user can also make one by clicking at https://ascii.rest/banner/.
Play one in a terminal
- Try any piece with nothing installed:
npx ascii.rest donut.npx ascii.rest banner "hello"prints a banner. - A splash screen for a Node CLI:
import { play } from "ascii.rest/terminal", thenawait play("donut", { seconds: 2 }). - A banner in a CLI's output:
await banner("my-cli")from the same module. - Piped or in CI,
play()draws nothing andbanner()prints the banner still, with no colour, so logs get no escape codes.
Details in references/docs/terminal.md.
Turn an image or a logo into ascii
- With no code: https://ascii.rest/make/ turns an image into a piece, with an embed snippet, a README snippet and the piece's source to copy.
- In code:
fromImage()fromascii.rest/kittakes any image in a browser, and PNG in Node.
See references/docs/images.md.
Make a new piece
Use the kit, ascii.rest/kit, and start with a recipe: one call by name, with options in words.
import { sea, spinning, torus, stars, pulsing, heart, gauge } from "ascii.rest/kit";
sea({ palette: "ocean" });
spinning(torus());
stars().behind(pulsing(heart())).named("love");
gauge({ label: "cpu", value: "64%" });
What the kit makes is a normal piece: pass it to <Ascii piece={...}>, mount(), svg() or play(). Go down to field(), scene(), particles(), picture() or piece() only when no recipe fits. npx ascii.rest play file.ts --watch plays a file's default export in the terminal while you edit it. Start at references/docs/kit.md.
Rules
- The npm package is
ascii.rest. It has no dependencies, and onlyascii.rest/reactneeds React. - A piece's name has dashes, like
night-coast. Its export fromascii.rest/piecesis in camelCase, likenightCoast. npx ascii.rest listprints 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"andimport 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>: setline-height: 1.2; margin: 0on it. The HTML tags and the Astro components set both for you. - Size a text piece with
font-size. Size a coloured piece withwidth(in React, instyle, not a class), and never set its height. - Colours are six-digit hex, like
#f97316.#fffandorangedon't work. banner()throws on an option it can't take.<Banner>and<ascii-banner>then draw nothing andconsole.warnwhy.- To turn an image into ascii in code, use
fromImage()fromascii.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 assea({ palette: "ocean" })orplasma().mask("HI"), motions such asspinning(torus())orfloating(heart()), widgets such asclockFace(),gauge({ label: "cpu", value: "64%" })orprogressBar(). Only when no recipe fits, go down tofield(),scene(),particles(),picture(),fromSvg(), effects such asglint(), layouts such asgrid(), orpiece()to draw on a grid. - Everything the kit makes is a normal piece: pass it to
<Ascii piece={...}>,mount(),svg()orplay(). It also chains:stars().behind(pulsing(heart())).named("love"). - Kit options take words:
speed: "slow",amount: "subtle",every: "rarely", a look'sscale: "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,heartand others share names with library pieces. In one file,import * as lib from "ascii.rest/pieces"and uselib.gaugebeside the kit'sgauge(). - In the kit, a frame should depend only on
t. Userandom(seed), neverMath.random(), and giveperiodorloopso an SVG loops.npx ascii.rest play file.ts --watchplays a file's default export in the terminal as you edit it.
When something is wrong
- Nothing shows. Check the name against references/pieces.md. With the HTML tags, check the closing tag is there and the script is a
type="module". Look in the console: a banner with an option it can't take warns why. - The rows are spaced apart. A text piece in React needs
line-height: 1.2; margin: 0on its<pre>; the HTML tags and Astro set them already. - The wrong size. A text piece takes
font-size; a canvas piece takeswidth(in React, instyle, not a class), neverheight. - It starts again on every render. A piece made during render, like
banner("hello")in JSX, is new each time: make it outside the component or inuseMemo, or use<Banner>. - It doesn't move. The reader's system asks for reduced motion, so it holds one frame, as it should. It also pauses off screen.
More in references/docs/faq.md.
The docs
Every page of https://ascii.rest/docs/, as plain Markdown. Read the one you need:
- introduction (start): What ascii.rest is, the ways to use it, and what its 236 pieces are.
- quick start (start): Get an animation on your page in under two minutes, with one script tag, with React or Next.js, or in your terminal.
- install (start): Add ascii.rest to your project from npm, with one script tag, or as source files you own.
- examples (start): 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.
- react (use it in): Play any piece, or draw any text as a banner, in a React or Next.js app.
- next.js (use it in): Play pieces and banners on Next.js pages, with the app router or the pages router, and serve banners as SVG images.
- astro (use it in): Add an animation or a text banner to an Astro page, with its first frame already in the HTML.
- html (use it in): Add animated ascii art and text banners to any web page with one script tag, no install and no build step.
- typescript (use it in): Play any piece on a web page with plain TypeScript and no framework, or draw its frames yourself.
- your own copy (use it in): Copy the TypeScript of any piece, the banner or the React components into your project, so you own it and can change it.
- banners (make): Draw any text in big block letters, then change its font, shadow, colours, motion and size.
- image to ascii (make): 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 (make): Turn any piece, or a banner of your own text, into an animated SVG that plays without JavaScript.
- github readme (make): Put a moving logo, or your name in big block letters, at the top of a GitHub README.
- terminal (make): 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 (make): Write your own animation as a piece, then play it in React, on any web page, as an SVG or in a terminal.
- the kit (make your own): 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 (make your own): 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 (make your own): Set anything moving in words, spinning, orbiting, bouncing, floating, pulsing, drifting, sliding in, with no angles and no maths.
- widgets (make your own): 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 (make your own): field() makes ascii art from a formula of x, y and t, the way a shader draws a picture. One function, one piece.
- drawing (make your own): Draw on a piece's grid with text, lines, boxes, circles, polygons, stamps, braille plots and pixel art, with no maths.
- maths (make your own): Noise, seeded randomness, easing, tweens, loops and a 3D camera, so a piece never writes its own.
- 3d scenes (make your own): 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 (make your own): particles() makes snow, rain, sparks, fireworks and systems of your own, said in words and plain numbers, looping exactly.
- effects (make your own): 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 (make your own): 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 (make your own): 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 (make your own): 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 (make your own): fromSvg() turns any SVG, from Figma, Illustrator or an icon set, into an ascii piece, and brings its parts to life by name.
- api (reference): Every function, component and type the ascii.rest package exports, with its signature and the page that shows it in use.
- cli (reference): Every command and flag of npx ascii.rest, what each one prints, and the exit codes it returns.
- questions (reference): Short answers to the questions people ask most, each with a link to the page that has the details.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/bas3line/ascii/ascii-rest">View ascii-rest on skillZs</a>