Emoji & Unicode Width Fix for xterm.js

Date: [Pre-October 2025 - before mouse coordinate fix] Status: ✅ SOLVED Issue: Emojis and wide Unicode characters broke terminal formatting and box drawing Time to Solution: 2 days of debugging Actual Solution: 1 line of code (install Unicode11 addon)

The Problem

When displaying emojis or wide Unicode characters in xterm.js terminals:

Expected:
┌─────────────┐
│ 📁 folder   │
│ 📄 file.txt │
└─────────────┘

Actual:
┌─────────────┐
│ 📁folder    │ ← Emoji width miscalculated
│ 📄file.txt  │ ← Box characters misaligned
└──────────   │ ← Bottom border broken

Symptoms:

Box drawing characters misaligned
Text after emojis positioned incorrectly
Table layouts broken
TUI apps (Bubbletea) rendering garbled
Double-width characters taking single width (or vice versa)

Root Cause: xterm.js uses a simplified Unicode width calculation by default. It doesn't properly handle:

Emoji (should be width 2)
Combining characters
Zero-width joiners
Unicode 11+ characters

The Solution

Install the Unicode11 addon:

// In Terminal.tsx
import { Terminal } from 'xterm';
import { Unicode11Addon } from 'xterm-addon-unicode11';  // ← Add this

// When creating the terminal:
xtermRef.current = new Terminal({
  // ... your options
});

// Load the Unicode11 addon:
const unicode11Addon = new Unicode11Addon();
xtermRef.current.loadAddon(unicode11Addon);
xtermRef.current.unicode.activeVersion = '11';  // ← This is the magic line

// Now emojis work perfectly! ✅

Install the package:

npm install xterm-addon-unicode11

That's it. 2 days of debugging, 1 line to fix.

Why This Was Hard to Find

Debugging attempts that didn't work:

❌ Adjusting terminal cols/rows
❌ Changing font sizes
❌ Different fonts (NerdFonts, etc.)
❌ CSS width adjustments
❌ Examining xterm.js source code
❌ Manual character width calculations
❌ Asking Claude/GPT (not in training data!)

What finally worked:

✅ Web search: "xterm.js emoji width broken"
✅ Found: Unicode11Addon in xterm.js documentation
✅ One line of code, instant fix

The Testing

Before Unicode11 addon:

Terminal with emojis:
┌─────────────┐
│ 📁folder    │ ← Broken
│ 📄file.txt  │ ← Broken
└──────────   │ ← Broken

After Unicode11 addon:

Terminal with emojis:
┌─────────────┐
│ 📁 folder   │ ← Perfect!
│ 📄 file.txt │ ← Perfect!
└─────────────┘ ← Perfect!

When You Need This

If you're building terminal apps with xterm.js and using:

Emojis in output (🎉, 📁, 📄, ✅, ❌, etc.)
TUI apps (Bubbletea, blessed, etc.)
Box drawing characters (┌─┐│└┘)
Table layouts with Unicode
Progress bars with Unicode block characters
Non-English text (CJK characters)

You NEED the Unicode11 addon.

Impact

Before:

TUI apps looked broken
Had to avoid emojis entirely
Box art wouldn't work
Reduced aesthetic options

After:

Perfect emoji rendering ✅
Beautiful TUI apps (tmuxplexer, TFE) ✅
Box characters work perfectly ✅
Can use full Unicode range ✅

This fix unlocked:

Building beautiful TUI tools
Using emojis in terminal output
Proper rendering of Bubbletea apps
Professional-looking terminal interfaces

The Lesson

Problem: LLMs (Claude/GPT) don't know about every addon/package Solution: Use web search for specific technical issues Better: Claude Code now has WebSearch built-in! Use it!

2 days could have been 5 minutes with:

> web search: xterm.js emoji width issues
→ First result: Unicode11 addon documentation
→ Problem solved

Code Example

Full working example:

import { Terminal } from 'xterm';
import { FitAddon } from 'xterm-addon-fit';
import { Unicode11Addon } from 'xterm-addon-unicode11';  // ← Critical

const terminal = new Terminal({
  fontFamily: 'JetBrains Mono Nerd Font, monospace',
  fontSize: 14,
  theme: {
    background: '#1a1a1a',
    foreground: '#ffffff',
  },
});

// Load Unicode11 addon
const unicode11 = new Unicode11Addon();
terminal.loadAddon(unicode11);
terminal.unicode.activeVersion = '11';  // ← The magic line

// Load fit addon
const fitAddon = new FitAddon();
terminal.loadAddon(fitAddon);

// Now emojis work! 🎉
terminal.write('📁 Projects\r\n');
terminal.write('📄 README.md\r\n');
terminal.write('✅ All formatting perfect!\r\n');

References

xterm.js Unicode11 Addon: https://github.com/xtermjs/xterm.js/tree/master/addons/xterm-addon-unicode11
xterm.js Addons: https://xtermjs.org/docs/guides/using-addons/
Unicode Width Issues: xtermjs/xterm.js#2450

This fix enabled building beautiful TUI tools. Without it, terminal apps look broken. With it, everything just works. 🎯

One line of code. Two days saved (if you know about it).

GGPrompts/EMOJI_WIDTH_FIX.md

Select an option

No results found