[BUG] Some emoji with variation selectors cause button layout misalignment in Ghostty terminal

[RMNCLDYO]

Some buttons containing emoji with Unicode variation selectors exhibit layout issues including misaligned borders and incorrect spacing when running in Ghostty terminal. The same code works correctly in macOS Terminal, indicating this is a terminal emulator compatibility issue rather than a Textual bug.

Steps to Reproduce

1. Create a simple Textual app with a button containing eye emoji:

from textual.app import App, ComposeResult
from textual.widgets import Button

class TestApp(App):
    def compose(self) -> ComposeResult:
        yield Button("👁️ Test")  # With variation selector - broken in Ghostty

TestApp().run()

2. Run the app in Ghostty terminal - observe misaligned borders
3. Run the same app in macOS Terminal - observe correct rendering
4. Compare with the Unicode escape version:

yield Button("\U0001F441 Test")  # Without variation selector - works in both terminals

Minimal Reproduction Code

from textual.app import App, ComposeResult
from textual.widgets import Button
from textual.containers import Vertical

class EmojiButtonTest(App):
    def compose(self) -> ComposeResult:
        yield Vertical(
            Button("👁️ With Variation Selector"),    # Broken in Ghostty only
            Button("\U0001F441 Without Variation Selector"),  # Works in both
            Button("👍 No Variation Selector Needed"),  # Works in both
            Button("❤️ Heart with VS"),              # Broken in Ghostty only
            Button("⭐️ Star with VS"),               # Works in both
            Button("Regular Button"),                 # Works in both
        )

if __name__ == "__main__":
    EmojiButtonTest().run()

Expected Behavior

All button variants should:

• Have identically aligned borders
• Maintain consistent spacing and padding
• Display the emoji characters properly
• Render consistently across different terminal emulators

Actual Behavior

In Ghostty terminal:

• 👁️ (eye with variation selector) - has misaligned borders and spacing issues
• ❤️ (heart with variation selector) - has misaligned borders and spacing issues
• ⭐️ (star with variation selector) - works fine
• Other buttons work correctly

In macOS Terminal:

• All buttons render correctly with proper alignment
• No layout issues with any emoji variants

Environment

• Textual version: 4.0.0
• Terminal: Ghostty 1.1.3 (issue present) / macOS Terminal (works correctly)
• OS: macOS Darwin 24.5.0
• Python version: 3.13.5

Additional Context

This issue only affects users running Textual applications in Ghostty terminal. The same applications work correctly in other terminal emulators like macOS Terminal.

I've opened a discussion in the Ghostty repository about this issue since it appears to stem from how Ghostty handles Unicode variation selector width calculations: Specific emoji with variation selectors cause layout issues in TUI applications

Pattern observed:

• 👍 (U+1F44D) - works in both terminals
• ⭐️ (U+2B50 + U+FE0F) - works in both terminals
• 👁️ (U+1F441 + U+FE0F) - broken in Ghostty only
• ❤️ (U+2764 + U+FE0F) - broken in Ghostty only

Impact

• Affects Textual applications only when run in Ghostty terminal
• Makes certain popular emoji unusable in Ghostty for Textual apps
• Users may experience inconsistent behavior across different terminals
• Not a widespread issue since it's terminal-specific

Workaround

For users experiencing this issue in Ghostty, use base Unicode characters without variation selectors:

# Instead of: Button("👁️ Watch") or Button("❤️ Love")
Button("\U0001F441 Watch")  # Eye without variation selector
Button("\U00002764 Love")   # Heart without variation selector

# Or switch to a different terminal emulator where the issue doesn't occur

Related Issues

• Ghostty Discussion #8027 - Discussion about the root cause in Ghostty's Unicode handling

Reproduction

Reproduction in Ghostty (showing layout issues)

Reproduction in Terminal (macOS) (showing correct rendering)

[github-actions]

We found the following entry in the FAQ which you may find helpful:

• Why doesn't Textual look good on macOS?

Feel free to close this issue if you found an answer in the FAQ. Otherwise, please give us a little time to review.

This project is developed and maintained by Will McGugan. Consider sponsoring Will's work on this project (and others).

This is an automated reply, generated by FAQtory

[TomJGooding]

...indicating this is a terminal emulator compatibility issue rather than a Textual bug.

Certain emoji take up double space within the terminal. Unfortunately, terminals don't always agree how wide a given character should be. ¹

This isn't an issue specific to Ghostty, but more importantly also not a Textual bug as you've already noted. If this isn't something Textual can fix, why create this issue?

Footnotes

1. Rich FAQ - Why does emoji break alignment ↩

[RMNCLDYO]

...indicating this is a terminal emulator compatibility issue rather than a Textual bug.

Certain emoji take up double space within the terminal. Unfortunately, terminals don't always agree how wide a given character should be. 1

This isn't an issue specific to Ghostty, but more importantly also not a Textual bug as you've already noted. If this isn't something Textual can fix, why create this issue?

Footnotes

1. Rich FAQ - Why does emoji break alignment ↩

@TomJGooding

You're absolutely right.

My thought process was that perhaps Textual might want to implement some kind of workaround or compatibility layer for these terminal inconsistencies.

I'll go ahead and close it!

[github-actions]

I hope I solved your issue!

Consider sponsoring my work to continue to maintain and develop Textual.

• Will McGugan

[00-kat]

Rich FAQ - Why does emoji break alignment ↩

From that FAQ:

Rich has no way of knowing how wide a character will be on any given terminal.

There is mode 2027 and the text sizing protocol's w flag. They're not too widely supported but they do exist, and the ones that do support it typically have this issue. (At the moment, only Kitty and Foot support the latter, and I don't remember who supports the former but I definitely know Ghostty, WezTerm, Contour, MinTTY, and maybe also Foot definitely support it.)

The easier solution is probably for users who care to set grapheme-width-method = legacy in their Ghostty configuration and deal with the other issues that show up (such as, in this case, the heart leaking into the next cell).

[TomJGooding]

@00-kat Intertesting, thanks. Shame it isn't more widely supported. The table in the related article you posted shows working with terminals is messy!

[RMNCLDYO]

Thank you @00-kat for clarification on the issue.

@TomJGooding might be helpful to add the FAQ's to the contribution guidelines, would've saved me some time - although I should've checked 😅.

Would love to see textual/rich implement mode 2027 or the text sizing protocols 'w' flag (or some other intuitive solution) to handle proper grapheme segmentation but as noted this will probably have incorrect results in many other terminal emulators.

Any thoughts here? @willmcgugan

I imagine this is not a high priority bug so I'll keep the issue closed.

Thanks again!

[danielwe]

as noted this will probably have incorrect results in many other terminal emulators

The way I read @00-kat in ghostty-org/ghostty#8027 (comment), implementing the protocol(s) would not lead to incorrect results; it would enable the best of both worlds.

Incorrect results would be the consequence of changing the hardcoded calculations to assume proper grapheme segmentation, without implementing any protocol(s).

[00-kat]

Yep, there wouldn't be an incorrect result because:

• From my understanding on mode 2027, if a terminal emulator says it supports mode 2027, you know how to calculate widths for it, and if it says it doesn't support it (or doesn't reply to the query), you can do whatever you're doing right now.
• With the text protocol's w flag, if you detect that the terminal emulator supports it with the query, you simply wrap the text with an OSC mentioning the size you want it to be rendered at, and if it doesn't support it you just print it out directly without wrapping it.

In either case, if it's not supported you're just back to what we're doing right now.

The thing that would result in incorrect results is unconditionally assuming wcwidth for all terminal emulators, or unconditionally doing full grapheme clustering for all terminal emulators.