How Terminals Work

Understanding a few terminal concepts will help you build better TUIs. This guide explains what happens when your Nocterm app runs.

The alternate screen

When you run a TUI app, it doesn't write to your normal terminal. Instead, it uses the alternate screen buffer.

Your terminal has two screens:

• Main screen: Your normal terminal where commands and output appear
• Alternate screen: A clean slate for full-screen apps

When a TUI starts, it switches to the alternate screen. When it exits, it switches back. Your command history and scrollback stay intact.

Try this:

1. Run a Nocterm app
2. Exit with Ctrl+C
3. Your terminal looks exactly like it did before

Nocterm automatically switches to the alternate screen when you call runApp(). You don't need to do anything.

Raw mode vs cooked mode

Terminals have two input modes that affect how they handle keyboard input.

Cooked mode (normal mode)

This is how your terminal normally works:

• Input is line-buffered (you type a line, press Enter, then the program sees it)
• Special keys work automatically (Ctrl+C exits, Ctrl+Z suspends)
• The terminal handles backspace, arrow keys, and line editing

Cooked mode is great for normal commands, but TUIs need more control.

Raw mode

In raw mode:

• Your app receives every key press immediately
• No special key handling—Ctrl+C is just another key
• You handle backspace, arrows, and everything else

TUIs need raw mode to respond to each key press and implement their own controls.

Nocterm switches to raw mode when your app starts and restores cooked mode when it exits. You don't configure this manually.

Terminal size

Terminals are grids measured in columns and rows. A typical terminal is 80 columns wide and 24 rows tall, but users can resize their windows.

When the user resizes the terminal, your app needs to redraw its UI. Nocterm handles this automatically:

• It detects resize events
• Rebuilds your component tree
• Redraws the UI to fit the new size

Your components receive the available space through their constraints, just like in Flutter.

Character cells

Terminals render text as a grid of character cells. Each cell contains:

• One character (a letter, number, emoji, or space)
• Styling (foreground color, background color, bold, italic, underline)

This is why TUI layout works differently from GUI apps:

• You position elements in rows and columns, not pixels
• Text wrapping happens at character boundaries
• Wide characters (like emoji or Chinese characters) can take up 2 cells

When you use Column, Row, and other layout components, Nocterm calculates positions in character cells and renders each cell with the correct character and style.

What Nocterm handles for you

You don't need to worry about most terminal mechanics:

• ✅ Alternate screen switching
• ✅ Raw mode setup and cleanup
• ✅ Resize event handling
• ✅ Cursor positioning
• ✅ Rendering optimization

Focus on building your UI. Nocterm handles the terminal.

Next steps

• ANSI Escape Codes - How terminals display colors and styles
• Terminal Limitations - Things to watch out for
• Components - Start building your UI