0
# @xterm/addon-unicode11
1

2
@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.
3

4
## Package Information
5

6
- **Package Name**: @xterm/addon-unicode11
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @xterm/addon-unicode11`
10
- **Peer Dependencies**: @xterm/xterm ^5.0.0
11

12
## Core Imports
13

14
```typescript
15
import { Unicode11Addon } from "@xterm/addon-unicode11";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { Unicode11Addon } = require("@xterm/addon-unicode11");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { Terminal } from "@xterm/xterm";
28
import { Unicode11Addon } from "@xterm/addon-unicode11";
29

30
// Create terminal and addon instances
31
const terminal = new Terminal();
32
const unicode11Addon = new Unicode11Addon();
33

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

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

40
// The terminal now uses Unicode 11 character width rules
41
// for proper rendering of modern Unicode characters and emojis
42
```
43

44
## Architecture
45

46
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.
47

48
Key components:
49
- **Unicode11Addon**: Main addon class implementing `ITerminalAddon`
50
- **UnicodeV11**: Internal Unicode provider implementing `IUnicodeVersionProvider`
51
- **Character width lookup tables**: Optimized tables for BMP and supplementary plane characters
52

53
## Capabilities
54

55
### Unicode11Addon Class
56

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

59
```typescript { .api }
60
/**
61
 * Unicode version 11 addon for xterm.js terminals
62
 * Implements ITerminalAddon interface for standard addon integration
63
 */
64
class Unicode11Addon implements ITerminalAddon {
65
  constructor();
66
  
67
  /**
68
   * Activates the addon on a terminal instance
69
   * Registers the Unicode V11 provider with the terminal's unicode registry
70
   * @param terminal - The xterm.js terminal instance to activate on
71
   */
72
  activate(terminal: Terminal): void;
73
  
74
  /**
75
   * Disposes of the addon resources
76
   * Currently a no-op implementation
77
   */
78
  dispose(): void;
79
}
80
```
81

82
**Usage Example:**
83

84
```typescript
85
import { Terminal } from "@xterm/xterm";
86
import { Unicode11Addon } from "@xterm/addon-unicode11";
87

88
const terminal = new Terminal();
89
const addon = new Unicode11Addon();
90

91
// Standard addon loading pattern
92
terminal.loadAddon(addon);
93

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

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

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

104
## Types
105

106
### ITerminalAddon Interface
107

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

110
```typescript { .api }
111
interface ITerminalAddon {
112
  activate(terminal: Terminal): void;
113
  dispose(): void;
114
}
115
```
116

117
### Terminal Integration
118

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

121
```typescript { .api }
122
// Available on terminal.unicode after loading the addon
123
interface UnicodeApi {
124
  versions: string[];           // Available Unicode versions (includes "11")
125
  activeVersion: string;        // Currently active version
126
  register(provider: IUnicodeVersionProvider): void;
127
}
128
```
129

130
## Character Width Behavior
131

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

134
- **Zero-width characters**: Combining marks, zero-width spaces, control characters
135
- **Full-width characters**: CJK characters, most emojis, fullwidth punctuation  
136
- **Half-width characters**: ASCII, most Latin characters, halfwidth symbols
137

138
This ensures proper:
139
- Text alignment and cursor positioning
140
- Character cell calculations for complex Unicode text
141
- Support for modern emojis and Unicode 11 additions
142

143
## Error Handling
144

145
The addon follows standard xterm.js patterns:
146
- No exceptions thrown during normal operation
147
- Terminal integration errors handled by xterm.js core
148
- Graceful fallback if Unicode version switching fails