DOCSEARCHbyAlgolia
Submit Docs

xterm.js

repository·master·Indexed 12 days ago

https://github.com/xtermjs/xterm.js

A high-performance frontend component that brings fully-featured terminal emulation to web browsers, used by applications like VS Code. Version 6.0.0 includes a core Terminal component and a variety of addons for functionality such as WebSocket attachment (@xterm/addon-attach), clipboard access (@xterm/addon-clipboard), terminal fitting (@xterm/addon-fit), programming ligatures (@xterm/addon-ligatures), and buffer searching (@xterm/addon-search).

Tokens
28.6K
Snippets
103
Records
135
Agent score
96%

What's inside xterm.js

  1. Understand ConEmu progress sequences and states

    master

    The @xterm/addon-progress addon implements the ConEmu progress sequence format: ESC ] 9 ; 4 ; <state> ; <progress value> BEL.

    State Meanings

    • 0 (Remove): Removes any progress indication and resets the value to 0. The addon always emits {state: 0, value: 0}.
    • 1 (Normal): Sets a progress value (0-100). If the value is omitted, it defaults to 0. Values are clamped to 100.
    • 2 (Error): An error state. If the value is omitted or 0, the addon emits the lastValue. If a value is provided, it is clamped to 100.
    • 3 (Indeterminate): Indicates a task is running without a specific progress percentage (e.g., a spinner). The progress value is ignored, but the addon emits {state: 3, value: lastValue}.
    • 4 (Pause/Warning): A pause or warning state. Similar to the error state, an omitted or zero value emits the lastValue. If a value is provided, it is clamped to 100.
    ESC ] 9 ; 4 ; <state> ; <progress value> BEL

  2. How addons work in xterm.js

    master

    Addons are separate modules that extend the Terminal functionality. To use an addon, you must:

    1. Install the specific addon package via npm.
    2. Import the addon class.
    3. Instantiate the addon and register it with the terminal instance using terminal.loadAddon().

    Example: Using WebLinksAddon

    import { Terminal } from '@xterm/xterm';
import { WebLinksAddon } from '@xterm/addon-web-links';

const terminal = new Terminal();
// Load WebLinksAddon on terminal to enable web link detection and interaction
terminal.loadAddon(new WebLinksAddon());
    import { Terminal } from '@xterm/xterm';
import { WebLinksAddon } from '@xterm/addon-web-links';

const terminal = new Terminal();
terminal.loadAddon(new WebLinksAddon());

  3. How to prevent layout issues with webfonts in xterm.js

    master

    xterm.js relies on exact character glyph measurements for its layout (DOM or WebGL). Because browsers often postpone loading large font files until they are explicitly needed, xterm.js might attempt to render using a fallback font before the webfont is ready. This results in incorrect glyph metrics and broken layouts.

    To prevent this, you must ensure webfonts are fully loaded before calling terminal.open().

  5. How @xterm/addon-ligatures works

    master

    Because xterm.js uses a canvas to render characters individually for performance, it cannot rely on the browser's native ligature rendering.

    @xterm/addon-ligatures works by:

    1. Locating the font file on the system disk for the font currently in use by the terminal.
    2. Parsing ligature information from that file (using the font-ligatures package).
    3. Annotating text as it is rendered so xterm.js can draw the ligatures correctly.

    Due to the need for disk access to resolve system fonts, this addon is designed for environments combining a browser and Node.js (e.g., Electron).

  6. Use @xterm/headless for Node.js environments

    master
    For environments without a browser (like pure Node.js), use @xterm/headless. This is a stripped-down version of xterm.js designed to run headlessly. A common use case is maintaining terminal state on a server and using the @xterm/addon-serialize addon to restore that state when a user reconnects.

  11. Load webfonts using the static loadFonts loader

    master

    If you prefer not to manage the WebFontsAddon instance lifecycle, you can use the static loadFonts function. This allows you to load fonts before any terminal setup occurs, effectively making the terminal setup synchronous once the fonts are ready.

    import { Terminal } from '@xterm/xterm';
import { XYAddon } from '@xterm/addon-xy';
// import static loader
import { loadFonts } from '@xterm/addon-web-fonts';

loadFonts(['Web Mono 1', 'Super Powerline']).then(() => {
  // fonts are already loaded, now create terminal
  const terminal = new Terminal({fontFamily: '"Web Mono 1", "Super Powerline", monospace'});
  const xyInstance = new XYAddon();
  terminal.loadAddon(xyInstance);

  // optional when using static loader
  const webfontsInstance = new WebFontsAddon();
  terminal.loadAddon(webfontsInstance);

  terminal.open(your_terminal_div_element);
});