Terminal.Gui — Cross-Platform TUI Toolkit for .NET

Introduction

Terminal.Gui is a cross-platform toolkit for building rich terminal user interfaces in .NET. It provides a window manager, layout engine, and a library of widgets (buttons, text fields, list views, tree views) that let you build desktop-style applications entirely in the terminal.

What Terminal.Gui Does

• Provides a full windowing system with overlapping and tiled windows in the terminal
• Ships with 40+ built-in widgets including buttons, text editors, list views, and tree views
• Offers a layout engine with absolute, computed, and auto-sizing positioning
• Handles keyboard navigation, mouse input, and clipboard operations cross-platform
• Supports 24-bit true color, Unicode, and bidirectional text rendering

Architecture Overview

Terminal.Gui uses a main loop pattern where Application.Run drives the event loop, dispatching keyboard, mouse, and timer events to the view hierarchy. Views are arranged in a tree rooted at Application.Top. The layout engine computes positions using a constraint-based system (Pos and Dim classes). Rendering is abstracted behind a ConsoleDriver interface with implementations for curses (Linux/macOS), Windows Console, and a headless driver for testing.

Self-Hosting & Configuration

• Install via NuGet: dotnet add package Terminal.Gui
• Targets .NET 8+ and also supports .NET Standard 2.0
• Works out of the box on Windows Terminal, iTerm2, xterm, and most Linux terminals
• Configure the color scheme globally or per-view using the ColorScheme class
• Use the built-in UI Catalog sample app to explore all widgets and layouts interactively

Key Features

• Desktop-style overlapping windows, modal dialogs, and menu bars in the terminal
• Comprehensive text editor widget with selection, undo/redo, and word wrap
• Built-in file and color picker dialogs
• Event-driven architecture with .NET events and async support
• Automated UI testing via the headless console driver

Comparison with Similar Tools

• Spectre.Console — focused on output rendering and prompts; Terminal.Gui provides full interactive TUI with windowing
• Textual (Python) — similar concept for Python; Terminal.Gui is the .NET counterpart
• Ratatui (Rust) — immediate-mode TUI; Terminal.Gui uses a retained-mode widget tree
• Bubble Tea (Go) — Elm-architecture TUI for Go; Terminal.Gui offers a more traditional event-driven model

FAQ

Q: Can I use Terminal.Gui in a web context? A: It is designed for terminal environments. For web, consider pairing it with a web-based terminal emulator.

Q: Does it support mouse input? A: Yes. Click, drag, scroll, and hover events are supported on terminals that report mouse events.

Q: How do I handle responsive layouts? A: Use computed Pos and Dim values (e.g., Dim.Fill(), Pos.Center()) which adjust to terminal size changes.

Q: Is there a visual designer? A: The community maintains a TUI designer prototype, and the UI Catalog app serves as an interactive reference.

Sources

• https://github.com/gui-cs/Terminal.Gui
• https://gui-cs.github.io/Terminal.GuiV2Docs/