A TypeScript/JavaScript port of Markus Kuhn’s wcwidth and wcswidth implementations, optimized to O(1).
These functions are defined in IEEE Std 1003.1 (POSIX).
Superior Performance
⚡️ Instant O(1) lookup time
🌏 Full Unicode 15.1 coverage
Getting Started
Install Wcwidth-O1 via npm:
npm i wcwidth-o1
Usage
JavaScript / TypeScript:
import wcwidth from 'wcwidth-o1' ; const example1 = wcwidth ( 'a' ) ; // 1 const example2 = wcwidth ( '好' ) ; // 2 const example3 = wcwidth ( '😊' ) ; // 2
or
import { wcwidth , wcswidth , wcswidthCjk } from 'wcwidth-o1' ; const example = wcwidth ( 'a' ) ; // 1 const example1 = wcswidth ( 'hi' ) ; // 2 const example2 = wcswidth ( '안녕하세요' ) ; // 10 const example3 = wcswidth ( '😊こんにちは' ) ; // 12 const example4 = wcswidthCjk ( '°C' ) ; // 3
Function Parameters:
wcwidth(), wcwidthCjk():
char : A single-character string to measure.
wcswidth(), wcswidthCjk():
str : Input string to evaluate.
: Input string to evaluate. n : Max characters to process (defaults to full length).
Behind Wcwidth
In fixed-width terminals, most Latin characters take up one column, while East Asian (CJK) ideographs usually take up two. The challenge is deciding how many “cells” each Unicode character should occupy so that text aligns correctly.
The Unicode standard defines width classes:
Wide (W) and Fullwidth (F) - always 2 columns
and - always 2 columns Halfwidth (H) and Narrow (Na) - always 1 column
and - always 1 column Ambiguous (A) - 1 column normally, but 2 in CJK compatibility mode
- 1 column normally, but 2 in CJK compatibility mode Neutral (N) - treated as 1 column here for simplicity
Other rules include:
U+0000 (null) - width 0
(null) - width 0 Control characters - -1
Combining marks - width 0
Soft hyphen ( U+00AD ) - width 1
) - width 1 Zero width space ( U+200B ) - width 0
This logic originates from Markus Kuhn’s reference implementation and is widely used in terminal emulators to ensure consistent alignment.
See Unicode TR#11 for more details.
Feedback
Found something odd?
Feel free to open an issue.
Acknowledgments
Original implementation by Markus Kuhn.
License