textmode.js

Appearance

Installation ​

Getting started with textmode.js is straightforward! This guide will walk you through the installation process for different environments and provide you with everything you need to begin creating ASCII art in the browser.

Prerequisites ​

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

  • A modern web browser with WebGL support (Chrome, Firefox, Safari, Edge, etc.)
  • A <canvas> or <video> element in your project (optional, for capturing content from a different source)
  • Node.js 16+ and npm (optional, for ESM installation)

Browser Compatibility

textmode.js uses WebGL1/WebGL2 with GLSL ES 1.0 shaders, ensuring broad compatibility across devices and browsers. Most modern browsers support WebGL by default.

Importing textmode.js ​

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

Bundle typeFile sizeFont included?Best for
Standard UMD (textmode.umd.js)~117kB✅ UrsaFont embeddedQuick setup, prototyping
Standard ESM (textmode.esm.js)~183kB✅ UrsaFont embeddedQuick setup, prototyping
Minified UMD (textmode.umd.min.js)~71kB❌ Requires external fontProduction apps, custom fonts
Minified ESM (textmode.esm.min.js)~136kB❌ Requires external fontProduction apps, custom fonts

Choose Standard bundles for:

  • Quick setup with no additional configuration
  • Everything embedded and ready to use
  • Getting started without worrying about fonts

Choose Minified bundles for:

  • Bundle size optimization (25-40% smaller)
  • Custom fonts instead of the default
  • Production applications requiring maximum performance

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:

html
<!DOCTYPE html>
<html>
<head>
    <title>textmode.js example</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>
    <canvas id="myCanvas" width="800" height="600"></canvas>
    <script>
        (async () => {
            // Reference your existing canvas element
            const canvas = document.querySelector('canvas#myCanvas');

            if (!canvas) {
                throw new Error('Canvas element not found');
            }

            // Standard bundle - no font configuration needed
            const textmodifier = await textmode.create(canvas);
            
            // Minified bundle - font required
            // const textmodifier = await textmode.create(canvas, {
            //     fontSource: './path/to/your/font.ttf'
            // });
        })();
    </script>
</body>
</html>

ESM ​

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

bash
npm install textmode.js

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

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

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

(async () => {
    // Reference your existing canvas element
    const canvas = document.querySelector('canvas#myCanvas');

    if (!canvas) {
        throw new Error('Canvas element not found');
    }

    // Standard bundle - no font configuration needed
    const textmodifier = await textmode.create(canvas);
    
    // Minified bundle - font required
    // const textmodifier = await textmode.create(canvas, {
    //     fontSource: './path/to/your/font.ttf'
    // });
})();

Verification ​

To verify your installation is working correctly, try this simple test:

javascript
// Test if textmode.js is available
console.log('textmode.js version:', textmode.version);

INFO

If you see the version number printed in the console, your installation was successful!

Getting Help ​

If you encounter issues:

  1. Check the examples for working implementations
  2. Join our Discord community for support
  3. Report bugs on GitHub Issues

Next Steps ​

Now that you have textmode.js installed, you're ready to start creating! Here's what to explore next:

Ready to Code?

Check out our Quick Start guide to create your first ASCII art in minutes!