@xterm/addon-unicode11

@xterm/addon-unicode11 provides Unicode version 11 character width rules for xterm.js terminal emulator. It enables accurate text rendering and cursor positioning for modern Unicode characters, emojis, and complex text by implementing Unicode 11 standards for character cell width calculations.

Package Information

• Package Name: @xterm/addon-unicode11
• Package Type: npm
• Language: TypeScript
• Installation: npm install @xterm/addon-unicode11
• Peer Dependencies: @xterm/xterm ^5.0.0

Core Imports

import { Unicode11Addon } from "@xterm/addon-unicode11";

For CommonJS:

const { Unicode11Addon } = require("@xterm/addon-unicode11");

Basic Usage

import { Terminal } from "@xterm/xterm";
import { Unicode11Addon } from "@xterm/addon-unicode11";

// Create terminal and addon instances
const terminal = new Terminal();
const unicode11Addon = new Unicode11Addon();

// Load the addon onto the terminal
terminal.loadAddon(unicode11Addon);

// Activate Unicode version 11 support
terminal.unicode.activeVersion = "11";

// The terminal now uses Unicode 11 character width rules
// for proper rendering of modern Unicode characters and emojis

Architecture

The addon integrates with xterm.js through the terminal's unicode registry system. When activated, it registers a Unicode version provider that implements Unicode 11 character width calculation rules. The addon follows the standard xterm.js addon pattern using the ITerminalAddon interface.

Key components:

• Unicode11Addon: Main addon class implementing ITerminalAddon
• UnicodeV11: Internal Unicode provider implementing IUnicodeVersionProvider
• Character width lookup tables: Optimized tables for BMP and supplementary plane characters

Capabilities

Unicode11Addon Class

Main addon class that provides Unicode version 11 support to xterm.js terminals.

/**
 * Unicode version 11 addon for xterm.js terminals
 * Implements ITerminalAddon interface for standard addon integration
 */
class Unicode11Addon implements ITerminalAddon {
  constructor();
  
  /**
   * Activates the addon on a terminal instance
   * Registers the Unicode V11 provider with the terminal's unicode registry
   * @param terminal - The xterm.js terminal instance to activate on
   */
  activate(terminal: Terminal): void;
  
  /**
   * Disposes of the addon resources
   * Currently a no-op implementation
   */
  dispose(): void;
}

Usage Example:

import { Terminal } from "@xterm/xterm";
import { Unicode11Addon } from "@xterm/addon-unicode11";

const terminal = new Terminal();
const addon = new Unicode11Addon();

// Standard addon loading pattern
terminal.loadAddon(addon);

// Unicode 11 is now available as a version option
console.log(terminal.unicode.versions); // includes "11"

// Activate Unicode 11 character width rules
terminal.unicode.activeVersion = "11";

// Test with Unicode 11 characters like modern emojis
terminal.write("🤣🤣🤣🤣🤣"); // Proper character width calculation

Types

ITerminalAddon Interface

Standard xterm.js addon interface (from @xterm/xterm):

interface ITerminalAddon {
  activate(terminal: Terminal): void;
  dispose(): void;
}

Terminal Integration

The addon integrates with the existing xterm.js Unicode system:

// Available on terminal.unicode after loading the addon
interface UnicodeApi {
  versions: string[];           // Available Unicode versions (includes "11")
  activeVersion: string;        // Currently active version
  register(provider: IUnicodeVersionProvider): void;
}

Character Width Behavior

When Unicode version 11 is active, the terminal uses the following character width rules:

• Zero-width characters: Combining marks, zero-width spaces, control characters
• Full-width characters: CJK characters, most emojis, fullwidth punctuation
• Half-width characters: ASCII, most Latin characters, halfwidth symbols

This ensures proper:

• Text alignment and cursor positioning
• Character cell calculations for complex Unicode text
• Support for modern emojis and Unicode 11 additions

Error Handling

The addon follows standard xterm.js patterns:

• No exceptions thrown during normal operation
• Terminal integration errors handled by xterm.js core
• Graceful fallback if Unicode version switching fails