# tcell — Terminal Cell Handling Library for Go

> tcell is a Go library for building terminal applications with support for true color, mouse events, Unicode, and wide characters. It provides a portable abstraction over diverse terminal emulators and is the foundation for popular TUI frameworks like tview.

## Install

Save in your project root:

# tcell — Terminal Cell Handling Library for Go

## Quick Use
```bash
# Add tcell to your Go project
go get github.com/gdamore/tcell/v2

# Minimal example: draw colored text
cat > main.go << 'EOF2'
package main

import (
    "github.com/gdamore/tcell/v2"
    "log"
)

func main() {
    s, err := tcell.NewScreen()
    if err != nil { log.Fatal(err) }
    if err := s.Init(); err != nil { log.Fatal(err) }
    defer s.Fini()

    style := tcell.StyleDefault.Foreground(tcell.ColorGreen)
    msg := "Hello, tcell!"
    for i, r := range msg {
        s.SetContent(i+2, 1, r, nil, style)
    }
    s.Show()
    s.PollEvent() // wait for any key
}
EOF2

go run main.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

---
Source: https://tokrepo.com/en/workflows/asset-0843efd5
Author: AI Open Source