DOCSEARCHbyAlgolia
Submit Docs

unblessed Documentation

website·Indexed 29 days ago

https://unblessed-docs.vercel.app/

A terminal user interface library providing a widget system for Node.js and browser platforms (via XTerm.js). Features a comprehensive set of widgets including Screen, Box, Layout, Table, List, and Textarea, along with a dedicated rendering pipeline and event handling system. Includes migration guides for users moving from blessed.

Tokens
172K
Snippets
1.4K
Records
1.7K
Agent score
73%

What's inside unblessed

  1. Overview of unblessed architecture and design principles

    unblessed is a TUI framework built on three fundamental principles: a platform-agnostic core (@unblessed/core) with zero platform dependencies, runtime dependency injection to allow the same code to run across different environments, and a modular package system where users install only the specific runtime they need (Node.js, Browser, or blessed compatibility).

  2. Overview of unblessed

    unblessed is a modern, TypeScript-first terminal UI library for building interactive command-line applications. It is built on top of the original blessed library and provides cross-platform support for both Node.js and browsers. Key advantages over the original blessed include full TypeScript type safety, browser support via XTerm.js, ESM + CJS builds, and a platform-agnostic architecture using runtime dependency injection.

  3. Overview of unblessed Terminal UI Library

    unblessed is a modern, TypeScript-first terminal user interface (TUI) library designed for use in both Node.js environments and web browsers. It provides a set of high-level components to build complex terminal applications, including layout containers, interactive inputs, and data displays.

  4. Overview of the unblessed TUI library

    unblessed is a modern, platform-agnostic terminal UI (TUI) library built with TypeScript. It is designed as a complete modernization of the original blessed library, maintaining 100% backward compatibility while providing strict TypeScript support and cross-platform capabilities (Node.js and browsers via XTerm.js). It supports both ESM and CJS builds.

  5. Overview of FileSystemAPI in unblessed runtime

    The FileSystemAPI is a subset of the Node.js fs module integrated into the unblessed runtime. It is primarily used for reading terminfo/termcap files, loading font definitions, logging, debugging, and temporary file operations.
    const runtime = getRuntime();
// Access file system methods via runtime.fs
const data = runtime.fs.readFileSync("/usr/share/terminfo/x/xterm");

  6. Use the Screen class as the root terminal container

    The Screen class is the top-level container and rendering engine for terminal UI applications. It manages the terminal's alt screen buffer, cursor control, and raw mode. It serves as the root of the widget tree, handles keyboard and mouse input events, manages widget focus, and provides an efficient rendering engine with smart CSR (Cursor Screen Refresh).

  7. Use the ProcessAPI for runtime process operations

    The ProcessAPI is a subset of the Node.js process global. It is used for managing I/O streams (stdin, stdout, stderr), accessing environment variables (e.g., TERM, EDITOR, HOME), handling process events (e.g., exit, SIGTSTP), and performing platform/architecture detection.
    const runtime = getRuntime();

// Access environment variables
const term = runtime.process.env.TERM || "xterm-256color";
const editor = runtime.process.env.EDITOR || "vi";
const home = runtime.process.env.HOME || "/";

  8. Query scroll state in OverlayImage

    Use these inherited methods to retrieve information about the current scroll position and the total scrollable area of an OverlayImage widget.
    // Get current absolute scroll position (in lines)
const currentScroll = overlayImage.getScroll();

// Get total height of the scrolling area
const totalHeight = overlayImage.getScrollHeight();

// Get current scroll position as a percentage (0-100)
const percentage = overlayImage.getScrollPerc();

  10. Use the Program class for low-level terminal control

    The Program class is the low-level interface between unblessed and the terminal. It manages I/O streams, converts high-level commands into terminal escape sequences, parses keyboard and mouse events, and optimizes output via buffer management. While it can be instantiated directly, it is typically created and managed by the Screen class.
    import { Screen } from "@unblessed/node";

const screen = new Screen();
const program = screen.program; // Access the Program instance

// Example low-level operations
program.clear();
program.cup(5, 10); // Move cursor to row 5, col 10
program.write("Hello!");

  12. Understand the unblessed rendering pipeline

    unblessed uses a smart rendering system to minimize terminal updates. The pipeline follows these steps:

    1. Dirty Tracking: Widgets are marked as 'dirty' when their content, style, or visibility changes.
    2. Screen Render: screen.render() is called to process all dirty widgets.
    3. Widget Rendering: Dirty widgets render their content to an internal buffer.
    4. Screen Diff: The system compares the new buffer with the previous frame to identify only the changed cells.
    5. Terminal Update: Only the diff (changed cells) is sent to the terminal as escape sequences.