wcwidth>=0.3 integration with iter_graphemes()

Author: jquast

CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [14.3.3] - 2026-02-02
+
+- Fixed width of more emojis and languages with new runtime module dependency wcwidth, https://github.com/Textualize/rich/pull/XXX
+
 ## [14.3.2] - 2026-02-01
 
 ### Fixed

CONTRIBUTORS.md

@@ -100,3 +100,4 @@ The following people have contributed to the development of Rich:
 - [Brandon Capener](https://github.com/bcapener)
 - [Alex Zheng](https://github.com/alexzheng111)
 - [Sebastian Speitel](https://github.com/SebastianSpeitel)
+- [Jeff Quast](https://github.com/jquast)

FAQ.md

@@ -100,13 +100,9 @@ See the docs on [console markup](https://rich.readthedocs.io/en/latest/markup.ht
 <a name="why-does-emoji-break-alignment-in-a-table-or-panel"></a>
 ## Why does emoji break alignment in a Table or Panel?
 
-Certain emoji take up double space within the terminal. Unfortunately, terminals don't always agree how wide a given character should be.
+Rich uses python wcwidth for character width measurement, which follows a [specification](https://wcwidth.readthedocs.io/en/latest/specs.html) that includes support for complex emoji and languages (grapheme clustering).
 
-Rich has no way of knowing how wide a character will be on any given terminal. This can break alignment in containers like Table and Panel, where Rich needs to know the width of the content.
-
-There are also *multiple codepoints* characters, such as country flags, and emoji modifiers, which produce wildly different results across terminal emulators.
-
-Fortunately, most characters will work just fine. But you may have to avoid using the emojis that break alignment. You will get good results if you stick to emoji released on or before version 9 of the Unicode database,
+Although *all* terminals do not fully support complex emoji, Rich support matches the correct presentation of many actively developed terminal emulators, tabulated and reported as [ucs-detect results](https://ucs-detect.readthedocs.io/results.html).
 
 <hr>
 

examples/emoji.py

@@ -0,0 +1,60 @@
+"""
+Demonstrates emoji, grapheme clusters, and multilingual text in tables and panels.
+
+Useful for visually testing terminal Unicode support.
+"""
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+console = Console()
+
+# Emoji and grapheme cluster table
+table = Table(title="Emoji & Grapheme Clusters")
+table.add_column("Type", style="cyan")
+table.add_column("Example", justify="center")
+table.add_column("Codepoints", style="dim")
+
+table.add_row(
+    "ZWJ Family",
+    "\U0001F468\u200D\U0001F469\u200D\U0001F467\u200D\U0001F466",
+    "4 emoji + 3 ZWJ",
+)
+table.add_row("Skin Tone", "\U0001F44B\U0001F3FD", "wave + modifier")
+table.add_row(
+    "Flags",
+    "\U0001F1FA\U0001F1F8 \U0001F1EC\U0001F1E7 \U0001F1EF\U0001F1F5",
+    "regional indicators",
+)
+table.add_row(
+    "VS16 Emoji", "\u2764\uFE0F \u2728 \u267B\uFE0F \u2615", "with variation selectors"
+)
+table.add_row(
+    "Keycap", "1\uFE0F\u20E3 2\uFE0F\u20E3 #\uFE0F\u20E3", "digit + VS16 + combining"
+)
+table.add_row("Combining", "e\u0301 n\u0303 u\u0308", "base + combining accent")
+table.add_row("CJK", "\u5bcc\u58eb\u5c71 \u6771\u4eac", "wide characters")
+
+console.print(table, justify="center")
+console.print()
+
+# Multilingual panel (UDHR Article 1 excerpts)
+text = (
+    "[bold]Universal Declaration of Human Rights, Article 1[/]\n\n"
+    "[cyan]English:[/]  All human beings are born free and equal in dignity.\n"
+    "[cyan]Arabic:[/]   \u064A\u0648\u0644\u062F \u062C\u0645\u064A\u0639"
+    " \u0627\u0644\u0646\u0627\u0633 \u0623\u062D\u0631\u0627\u0631\u0627\n"
+    "[cyan]Hindi:[/]    \u0938\u092D\u0940 \u092E\u0928\u0941\u0937\u094D\u092F\u094B\u0902"
+    " \u0915\u094B \u0917\u094C\u0930\u0935 \u0914\u0930"
+    " \u0905\u0927\u093F\u0915\u093E\u0930\u094B\u0902\n"
+    "[cyan]Thai:[/]     \u0E21\u0E19\u0E38\u0E29\u0E22\u0E4C\u0E17\u0E31\u0E49\u0E07"
+    "\u0E2B\u0E25\u0E32\u0E22\u0E40\u0E01\u0E34\u0E14\u0E21\u0E32\n"
+    "[cyan]Japanese:[/] \u3059\u3079\u3066\u306E\u4EBA\u9593\u306F\u3001"
+    "\u751F\u307E\u308C\u306A\u304C\u3089\u306B\u3057\u3066\n"
+    "[cyan]Korean:[/]   \ubaa8\ub4e0 \uc0ac\ub78c\uc740 \ud0dc\uc5b4\ub0a0 "
+    "\ub54c\ubd80\ud130 \uc790\uc720\ub85c\uc6b0\uba70\n"
+    "[cyan]Tibetan:[/]  \u0F66\u0F90\u0FB1\u0F7A\u0F0B\u0F56\u0F7C\u0F0B"
+    "\u0F58\u0F72\u0F0B\u0F62\u0F72\u0F42\u0F66\u0F0B\u0F40\u0F72"
+)
+console.print(Panel(text, title="\U0001F30D Languages", border_style="blue"))

poetry.lock

@@ -30,6 +30,7 @@ include = ["rich/py.typed"]
 [tool.poetry.dependencies]
 python = ">=3.8.0"
 pygments = "^2.13.0"
+wcwidth = ">=0.5.3"
 ipywidgets = { version = ">=7.5.1,<9", optional = true }
 markdown-it-py = ">=2.2.0"
 

pyproject.toml

@@ -2,10 +2,6 @@
 title: "Why does emoji break alignment in a Table or Panel?"
 ---
 
-Certain emoji take up double space within the terminal. Unfortunately, terminals don't always agree how wide a given character should be.
+Rich uses python wcwidth for character width measurement, which follows a [specification](https://wcwidth.readthedocs.io/en/latest/specs.html) that includes support for complex emoji and languages (grapheme clustering).
 
-Rich has no way of knowing how wide a character will be on any given terminal. This can break alignment in containers like Table and Panel, where Rich needs to know the width of the content.
-
-There are also *multiple codepoints* characters, such as country flags, and emoji modifiers, which produce wildly different results across terminal emulators. 
-
-Fortunately, most characters will work just fine. But you may have to avoid using the emojis that break alignment. You will get good results if you stick to emoji released on or before version 9 of the Unicode database, 
+Although *all* terminals do not fully support complex emoji, Rich support matches the correct presentation of many actively developed terminal emulators, tabulated and reported as [ucs-detect results](https://ucs-detect.readthedocs.io/results.html).