Unicode text can contain more characters than a terminal column model can describe with a simple string length. This guide explains why tables, logs, prompts, and progress bars become misaligned, how combining marks, CJK characters, emoji sequences, and ambiguous-width symbols are measured, and how to build a repeatable workflow around wcwidth-style libraries and real terminal testing.
Overview
A terminal usually positions text on a grid of cells. A character may occupy zero, one, or two cells, but the number of programming-language characters is not the same as the number of visible terminal columns. For example, an accented letter may be represented as a base letter followed by a combining mark. The string contains multiple code points, while the rendered result may occupy one cell. A CJK ideograph commonly occupies two cells in terminals that use a wide presentation. An emoji sequence may contain several code points but appear as one visual symbol, with its terminal width depending on the sequence and emulator.
This distinction is the reason that len(), JavaScript string length, UTF-16 code-unit counts, and byte length are unsafe for padding or truncating terminal output. A terminal table needs a display-width calculation, not merely a character count. Even a display-width calculation is an approximation: the terminal emulator, font, locale, Unicode data version, and application library all influence the result.
The practical model is to separate three questions:
- How is the text encoded? Bytes and code points answer this question.
- How is the text segmented? Grapheme clusters describe user-perceived characters such as a base letter plus marks or an emoji joined with a zero-width joiner.
- How many terminal cells does it occupy? A
wcwidth-style function provides the operational answer needed for columns.
For related Unicode behavior in applications, see the guides to Unicode normalization and Unicode emoji sequences. Normalization and emoji composition do not automatically solve terminal alignment, but they help explain why visible symbols and code-point counts differ.
What to track
Terminal width categories
Use the following table as a diagnostic model rather than an absolute rendering guarantee. Width values describe common terminal behavior, not the number of code points in the input.
| Text type | Typical cell width | Why it affects alignment | Example |
|---|---|---|---|
| Combining marks | 0, after a base character | A mark modifies a preceding character and normally does not advance the cursor by itself. | e with a combining acute accent |
| Narrow characters | 1 | ASCII letters, digits, punctuation, and many other characters advance one cell. | A7-OK |
| Wide CJK characters | 2 | Many Han, Hiragana, Katakana, and Hangul characters are rendered across two cells. | 日本語 |
| Emoji sequences | Often 2, but sequence-dependent | Variation selectors, skin-tone modifiers, and zero-width joiners can combine several code points into one displayed symbol. | 👩💻 or 👍🏽 |
| Ambiguous-width symbols | 1 or 2 | Symbols classified as East Asian Ambiguous may be narrow in one context and wide in another. | ·, Ω, or selected box and math symbols |
The exact characters in an example can be difficult to inspect in source code, so test with code-point inspection when diagnosing a defect. A useful diagnostic record includes the original string, its escaped representation, code points, Unicode names where available, grapheme clusters, calculated cell width, locale, terminal emulator, and font. This turns a visual complaint such as “the second column shifts” into a reproducible case.
Width data and library behavior
wcwidth-style libraries generally classify characters using Unicode properties and compatibility tables. They may disagree on newer characters, emoji sequences, control characters, or ambiguous-width handling. Some libraries calculate each code point independently and therefore do not fully model grapheme clusters or joined emoji. Others add special handling for sequences.
Check whether your chosen library exposes separate functions for one character and a full string, how it treats control characters, which Unicode version its tables reflect, and whether it offers an option for ambiguous-width characters. Do not assume that a library's result is identical to the terminal you are using.
Operations that require cell-aware logic
Four operations commonly expose width bugs:
- Padding: subtract the measured cell width from the target width, not the string length.
- Truncation: stop before the next grapheme cluster would exceed the cell budget, then add an ellipsis only if its own width fits.
- Column layout: calculate the maximum display width of each column before emitting separators.
- Progress bars: reserve space for labels, symbols, and terminal control sequences separately from visible text.
ANSI color sequences, cursor movement commands, and other escape sequences occupy bytes but normally occupy zero terminal cells. Strip or parse them before measuring visible width. A regular expression that removes only one common color pattern may fail on other control sequences, so prefer a terminal-aware parser when output includes complex styling.
Cadence and checkpoints
Terminal width is a recurring compatibility concern. Review it when the output surface or its dependencies change, rather than waiting for a user to report a broken table.
At implementation time
Create a small fixture containing narrow Latin text, combining-mark text, precomposed accented text, CJK text, ambiguous symbols, flags, skin-tone emoji, and a zero-width-joiner emoji. Record expected behavior as cell widths and visual alignment, not just snapshots of raw strings. Include empty text, control characters, very long labels, and text that ends with a combining mark.
Test both padding and truncation. Padding can reveal an incorrect width calculation while truncation can reveal a more serious bug: cutting between code points may leave an orphaned combining mark or split an emoji sequence. If your application supports multiple output modes, test plain text, colored text, and machine-readable output separately.
On a monthly or quarterly maintenance cycle
Check the Unicode data version used by the runtime or width library, review dependency updates, and rerun the fixture in the terminals your users actually use. Compare at least one local terminal with a continuous-integration environment if snapshots or golden files are part of the test suite. Recheck the behavior of ambiguous-width symbols whenever locale or East Asian display settings are part of your product's configuration.
Keep a short compatibility note in the project documentation: the width library and version, supported terminal assumptions, treatment of ambiguous characters, and known limitations for emoji. This prevents a future dependency upgrade from silently changing table geometry.
When adding multilingual output
Run a focused checkpoint whenever a new language, locale, font, or translation is introduced. Translators may provide composed or decomposed text, and a label that fits in one language may be much wider in another. Include real translated strings in layout tests rather than relying only on ASCII placeholders.
How to interpret changes
When output shifts, first determine whether the failure is in measurement or rendering. Print the same fixture with width numbers beside each string. If the library reports a width that differs from what the terminal visibly displays, isolate the terminal, locale, font, and library version. If the reported widths are consistent but columns still move, inspect padding arithmetic, hidden ANSI sequences, tabs, carriage returns, and line-wrapping behavior.
A useful investigation sequence is:
- Reduce the case: replace the full log or table with two labels and one separator.
- Inspect code points: identify combining marks, variation selectors, joiners, modifiers, and control characters.
- Measure layers separately: compare byte length, code-point count, grapheme-cluster count, and terminal cell width.
- Test the width library: call the single-character function for each code point and the string function for the complete sequence.
- Test the terminal: render the same data in each supported emulator and locale.
- Choose a policy: document whether ambiguous characters are treated as narrow, wide, or unsupported.
Do not “fix” misalignment by adding a constant space after every non-ASCII character. That may make one CJK example appear correct while breaking combining marks, emoji, and mixed-language labels. Likewise, converting all text to NFC can improve consistency for accented text but does not make every emoji sequence one code point or guarantee a particular terminal width.
For application boundaries, also verify that text has not been escaped incorrectly or decoded twice. The guide to Unicode escapes in HTML, CSS, JavaScript, and JSON can help distinguish an encoding problem from a terminal-width problem.
When to revisit
Revisit this guide and your test fixtures when you upgrade a Unicode-aware dependency, change runtime versions, support a new terminal emulator, add CJK or multilingual output, introduce emoji-rich labels, change locale handling, or receive a report about shifted columns. A quarterly review is a sensible default for actively maintained command-line tools; a monthly check is appropriate during a release cycle that changes rendering or internationalization.
Make the next review practical:
- Run the fixture through the same
wcwidth-style library used in production. - Render it in each supported terminal and capture screenshots only as supplemental evidence.
- Compare calculated widths with visible cursor movement or known column boundaries.
- Review truncation at grapheme-cluster boundaries and verify that ellipses fit the budget.
- Record any changed behavior with the terminal, locale, library, and Unicode data version.
The goal is not to make every terminal render every symbol identically. The goal is to define a clear width policy, measure text consistently, test the important environments, and fail safely when a sequence cannot be modeled. Treating terminal width as a compatibility surface makes Unicode alignment bugs diagnosable instead of mysterious.