textmode.js (✿◠‿◠)

textmode.js is a free, lightweight, and framework-agnostic creative-coding library for real‑time ASCII and textmode graphics in the browser. It combines a grid‑based API with a modern WebGL2 pipeline, multiple render targets, and aggressive instanced rendering to deliver smooth, high‑performance rendering.

The library is designed to be easy to use and accessible to developers of all skill levels. Whether you're a seasoned developer or just starting out, textmode.js provides a simple and intuitive API that makes it easy to create stunning textmode art and animations.

Features

Real‑time* ASCII/textmode rendering with a simple drawing API
WebGL2 pipeline with Multiple Render Targets (MRT) for rich per‑cell data
Instanced rendering and batching for low draw call counts
Font system with runtime font loading and dynamic sizing (supports TTF/OTF/WOFF)
Author custom filter shaders in GLSL ES 3.00 for advanced effects
Flexible exporting: TXT, SVG, raster images (PNG/JPG/WebP), animated GIFs, and video (WebM)
Animation loop control: frameRate, loop/noLoop, redraw, frameCount, etc.
Framework-agnostic: Use textmode.js with any canvas-based framework or library
Zero dependencies, written in TypeScript, with comprehensive type definitions

Note

*Performance depends on the complexity of your scene and device capabilities. Consider authoring filter shaders for complex effects at low cost.

Try it online first

Before installing anything locally, you can try textmode.js directly in your browser using our dedicated web editor:

🌐 editor.textmode.art

The web editor is specifically designed for textmode.js and provides:

✨ Zero setup required - Start coding immediately
🚀 Live preview - See your creations in real-time
💾 Save & share - Export your sketches and share with others
📚 Built-in examples - Learn from interactive examples
🔧 Full API access - All textmode.js features available

The web editor is perfect for learning, prototyping, or creating quick experiments without any local setup!

Installation

Prerequisites

To get started with textmode.js, you'll need:

A modern web browser with WebGL2 support (Chrome, Firefox, Safari, Edge, etc.)
A <canvas> in your project (optional, otherwise the library will create one for you)
Node.js 16+ and npm (optional, for ESM installation)

Important

textmode.js is currently fully dependent on WebGL2. Ensure your target browsers support it. You can check compatibility on caniuse.com.

Importing `textmode.js`

textmode.js is available in multiple bundle variants to suit different project needs:

Bundle type	File size	Font included?	Best for
Standard UMD (`textmode.umd.js`)	~87kB	✅ UrsaFont embedded	Quick setup, prototyping
Standard ESM (`textmode.esm.js`)	~111kB	✅ UrsaFont embedded	Quick setup, prototyping
Minified UMD (`textmode.umd.min.js`)	~79kB	❌ Requires external font	Custom fonts
Minified ESM (`textmode.esm.min.js`)	~103kB	❌ Requires external font	Custom fonts

Choose standard bundles for:

Quick setup with no additional configuration
Production applications that use the embedded font

Choose minified bundles for:

Production applications that don't use the embedded font

Note

Apart from the font inclusion, both bundle types are functionally identical and equally minified.

UMD

To use textmode.js in a UMD environment, download the latest umd build from the GitHub releases page or import it directly from a CDN like jsDelivr. The library is distributed as a single JavaScript file, which you can include in your project by adding the following script tag to your HTML file:

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
    <title>textmode.js sketch</title>

    <!-- Standard bundle (with embedded UrsaFont) -->
    <script src="https://cdn.jsdelivr.net/npm/textmode.js@latest/dist/textmode.umd.js"></script>
    
    <!-- OR Minified bundle (requires external font) -->
    <!-- <script src="https://cdn.jsdelivr.net/npm/textmode.js@latest/dist/textmode.umd.min.js"></script> -->
</head>
<body>
    <script src="sketch.js"></script>
</body>
</html>

// sketch.js
const t = textmode.create({
    width: window.innerWidth,
    height: window.innerHeight,
    fontSize: 16,
    frameRate: 60
});

t.setup(() => {
    // Optional setup code here (e.g., load fonts/shaders, initialize variables that access 't')
});

t.draw(() => {
    t.background(32); // Dark gray background

    t.char('A');
    t.charColor(255, 0, 0); // Cover the top-left quarter of the grid with a rectangle of red 'A's
    t.rect(0, 0, t.grid.cols / 2, t.grid.rows / 2);

    // ...add your drawing code here!
});

t.windowResized(() => {
    t.resizeCanvas(window.innerWidth, window.innerHeight);
});

ESM

To use textmode.js in an ESM environment, you can install it via npm:

npm install textmode.js

Then, you can import it in your JavaScript or TypeScript files:

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>textmode.js sketch</title>
</head>
<body>
    <script type="module" src="./sketch.js"></script>
</body>
</html>

// sketch.js
// Standard bundle (with embedded UrsaFont)
import { textmode } from 'textmode.js';

// OR Minified bundle (requires external font)
// import { textmode } from 'textmode.js/min';

const t = textmode.create({
    width: window.innerWidth,
    height: window.innerHeight,
    fontSize: 16,
    frameRate: 60
});

t.setup(() => {
    // Optional setup code here (e.g., load fonts/shaders, initialize variables that access 't')
});

t.draw(() => {
    t.background(32); // Dark gray background

    t.char('A');
    t.charColor(255, 0, 0); // Cover the top-left quarter of the grid with a rectangle of red 'A's
    t.rect(0, 0, t.grid.cols / 2, t.grid.rows / 2);

    // ...add your drawing code here!
});

t.windowResized(() => {
    t.resizeCanvas(window.innerWidth, window.innerHeight);
});

Next steps

Now that you have textmode.js set up, you can start creating your textmode art projects! Going forward, here are some resources to help you get the most out of the library:

📚 Visit the Official Documentation for detailed guides, interactive examples, complete API reference, tips and tricks, and much more to unlock the full potential of textmode.js in your creative coding projects.

🎨 Try the Web Editor to experiment with textmode.js without setting up a local environment.

Acknowledgements

textmode.js uses a custom-made TypeScript rewrite and minified version of Typr.js by Photopea for font loading and parsing, containing only the necessary components for our use case. Typr.js is licensed under the MIT License.

The non-minified version of textmode.js ships with UrsaFont as the default font, created by UrsaFrank. This font is available under the CC0 (Creative Commons Zero) license.

humanbydefinition/textmode.js