tcell — Terminal Cell Handling Library for Go

Introduction

tcell provides a low-level, cell-based API for interacting with terminal emulators from Go. It normalizes differences across terminals (xterm, iTerm2, Windows Console, tmux, screen) so that applications handle a consistent set of events and drawing primitives. It supports true color (24-bit), 256 colors, mouse input, and Unicode including CJK wide characters.

What tcell Does

• Abstracts terminal differences behind a unified Screen interface for portable TUI code
• Supports true color (24-bit RGB), 256-color, and 16-color terminal modes with automatic fallback
• Handles mouse events including clicks, scrolling, and motion tracking
• Renders Unicode text with proper handling of wide characters, combining marks, and BiDi
• Provides an event-driven API with keyboard, mouse, and resize events

Architecture Overview

tcell manages a virtual screen buffer where each cell holds a rune, combining characters, and a style (foreground, background, attributes). When Show() is called, tcell computes the minimal set of terminal escape sequences needed to update the physical display from the virtual buffer. Terminal capabilities are loaded from a built-in database (replacing the need for terminfo files on most systems). The event loop translates raw terminal input into typed Go events.

Self-Hosting & Configuration

• Add the dependency: go get github.com/gdamore/tcell/v2
• No CGo or external C libraries required; pure Go for easy cross-compilation
• Override terminal detection with the TERM environment variable if needed
• Register custom terminal types with tcell.RegisterTerminfo() for unsupported terminals
• Set encoding explicitly with s.SetEncoding() for non-UTF-8 environments

Key Features

• Built-in terminal database covers 100+ terminal types without requiring system terminfo
• Thread-safe screen operations allow concurrent updates from multiple goroutines
• Efficient differential rendering only sends changed cells to the terminal
• Windows Console support works natively without requiring Cygwin or WSL
• Synchronized output support (DEC mode 2026) prevents screen tearing in fast-updating UIs

Comparison with Similar Tools

• tview — tview builds high-level widgets on top of tcell; tcell is the low-level rendering layer
• termbox-go — termbox-go is simpler but less maintained and lacks true color, mouse support, and wide character handling
• bubbletea/lipgloss — The Charm stack uses its own terminal library; tcell is an alternative foundation with broader terminal support
• crossterm (Rust) — crossterm provides similar cross-platform terminal abstraction for Rust; tcell is the Go equivalent
• ncurses — ncurses is a C library with Go bindings; tcell is a pure Go alternative that avoids CGo complexity

FAQ

Q: Does tcell work on Windows? A: Yes. tcell supports Windows Console natively, including mouse and color support, without Cygwin or WSL.

Q: How do I handle terminal resizing? A: Listen for *tcell.EventResize in the event loop and call s.Sync() to recalculate the screen dimensions.

Q: Can tcell render true color (24-bit)? A: Yes. Use tcell.NewRGBColor(r, g, b) for styles. tcell automatically falls back to 256 or 16 colors on limited terminals.

Q: Is tcell suitable for high-frequency updates? A: Yes. Differential rendering and synchronized output support make tcell efficient for dashboards and animations.

Sources

• https://github.com/gdamore/tcell
• https://pkg.go.dev/github.com/gdamore/tcell/v2
• https://github.com/gdamore/tcell/blob/main/README.md