Terminal Limitations

Terminals have limitations that affect how you build TUIs. This guide explains what to watch out for and how to build apps that work everywhere.

Not all terminals are equal

Different terminal emulators support different features. A feature that works in one terminal might not work in another.

Common variations:

• Color support: Some terminals only support 16 colors, others support millions
• Text styles: Italic works in some terminals but not others
• Mouse support: Not all terminals support mouse input
• Unicode rendering: Emoji and special characters vary widely

Nocterm handles many differences automatically by using widely-supported ANSI codes. When you use TextStyle(color: Colors.red), Nocterm picks an approach that works on most terminals.

Note: Test your app on the terminals your users will use. The three most common are: macOS Terminal, iTerm2, and Windows Terminal.

Unicode and emoji

Basic ASCII characters (letters, numbers, punctuation) work everywhere. Beyond that, support gets inconsistent.

What usually works

• Common Unicode characters (accented letters like é, ñ, ü)
• Basic symbols (→, ✓, ✗)
• Box-drawing characters (─, │, ┌, ┐)

What's unreliable

• Emoji: Some terminals display emoji as images, others as text, others not at all
• Wide characters: Chinese, Japanese, and Korean characters take up 2 cells, but some terminals miscalculate width
• Combining characters: Accents added separately (like e + ´ = é) can render incorrectly

If you use emoji or fancy Unicode:

• Test on multiple terminals
• Provide alternatives (use [X] instead of ✓ if needed)
• Don't rely on precise width calculations for wide characters

Terminal size matters

Users run terminals in different sizes. Some use small windows, others use full-screen terminals.

Design for small sizes

The classic terminal is 80 columns × 24 rows. Many users still use this size or smaller. Design your UI to work in 80×24:

• Keep important content above the fold
• Use scrolling for long lists
• Don't assume width above 80 columns

Test your app at 80×24 to catch layout issues.

Handle resizing

Users resize terminal windows while your app runs. Nocterm rebuilds your UI automatically when this happens, but you should:

• Use flexible layouts (Expanded, Column, Row)
• Test how your UI looks at different sizes
• Add scrolling for content that might overflow

Avoid fixed sizes. Let your components adapt to available space.

Performance considerations

Terminals aren't as fast as GUI frameworks. Drawing happens by sending text to the terminal, which is slower than rendering pixels.

What affects performance

• Redrawing the entire screen: Slow on large terminals
• Frequent updates: Redrawing 60 times per second can overwhelm terminals
• Large amounts of text: Rendering thousands of lines takes time

What Nocterm does

Nocterm optimizes rendering:

• Updates only changed parts of the screen
• Batches output to reduce system calls
• Skips redraws when nothing changed

You don't need to optimize manually, but avoid:

• Rebuilding the UI on every frame
• Rendering huge lists without scrolling

Mouse support

Not all terminals support mouse input. Even when they do, support varies:

• Some support clicks only
• Some support drag events
• Some support scroll wheel events

Best practices

• Always provide keyboard alternatives: Every action should have a keyboard shortcut
• Treat mouse as optional: Your app should work without a mouse
• Test without mouse: Make sure you can do everything with just the keyboard

Nocterm supports mouse events when the terminal supports them, but your app shouldn't require them.

Best practices for robust TUIs

Follow these guidelines to build TUIs that work everywhere:

Test on multiple terminals

Don't just test on your favorite terminal. Test on:

• macOS Terminal (common on Mac)
• iTerm2 (popular Mac alternative)
• Windows Terminal (Windows 10/11 default)
• Your target users' terminals

Design for keyboard-first

• Every feature should have a keyboard shortcut
• Show keyboard hints in your UI
• Make tab navigation work

Use common characters

• Stick to ASCII when possible
• Use box-drawing characters for borders
• Avoid emoji unless you've tested them

Handle errors gracefully

• Catch terminal size too small
• Handle color display issues
• Provide fallbacks for unsupported features

Document requirements

Tell users what terminals work best:

• Recommended terminal size
• Required terminal features (colors, mouse)
• Known compatibility issues

Next steps

• Components - Build your UI with confidence
• Testing - Test across different scenarios
• Keyboard Events - Make your app keyboard-friendly