Convert Figma logo to code with AI

gdamore logotcell

Tcell is an alternate terminal package, similar in some ways to termbox, but better in others.

4,987
334
4,987
28

Top Related Projects

Pure Go termbox implementation

13,161

Terminal UI library with rich, interactive widgets — written in Golang

13,461

Golang terminal dashboard

10,432

Minimalist Go package aimed at creating Console User Interfaces.

2,113

A UI library for terminal applications.

Terminal based dashboard.

Quick Overview

Tcell is a Go package that provides a low-level, terminal-independent library for creating text-based user interfaces. It offers a cross-platform solution for building terminal applications with advanced features like color support, mouse input, and Unicode handling.

Pros

  • Cross-platform compatibility (works on Windows, macOS, and Linux)
  • Rich feature set including color support, mouse input, and Unicode handling
  • Efficient and low-level API for fine-grained control
  • Active development and community support

Cons

  • Steeper learning curve compared to higher-level TUI libraries
  • Requires more code to implement complex UI elements
  • Limited built-in widgets or pre-made components
  • Documentation could be more comprehensive for beginners

Code Examples

  1. Basic screen initialization and event handling:
package main

import (
    "fmt"
    "os"

    "github.com/gdamore/tcell/v2"
)

func main() {
    screen, err := tcell.NewScreen()
    if err != nil {
        fmt.Fprintf(os.Stderr, "%v\n", err)
        os.Exit(1)
    }
    if err := screen.Init(); err != nil {
        fmt.Fprintf(os.Stderr, "%v\n", err)
        os.Exit(1)
    }
    defer screen.Fini()

    for {
        switch ev := screen.PollEvent().(type) {
        case *tcell.EventKey:
            if ev.Key() == tcell.KeyEscape {
                return
            }
        }
    }
}
  1. Drawing text on the screen:
screen.Clear()
style := tcell.StyleDefault.Foreground(tcell.ColorRed).Background(tcell.ColorBlack)
row, col := 1, 1
str := "Hello, Tcell!"
for _, r := range str {
    screen.SetContent(col, row, r, nil, style)
    col++
}
screen.Show()
  1. Handling mouse events:
switch ev := screen.PollEvent().(type) {
case *tcell.EventMouse:
    x, y := ev.Position()
    button := ev.Buttons()
    if button == tcell.ButtonPrimary {
        fmt.Printf("Left click at (%d, %d)\n", x, y)
    }
}

Getting Started

To use Tcell in your Go project, follow these steps:

  1. Install Tcell:

    go get -u github.com/gdamore/tcell/v2
    
  2. Import Tcell in your Go file:

    import "github.com/gdamore/tcell/v2"
    
  3. Initialize a screen:

    screen, err := tcell.NewScreen()
    if err != nil {
        // Handle error
    }
    if err := screen.Init(); err != nil {
        // Handle error
    }
    defer screen.Fini()
    
  4. Start handling events and drawing to the screen using the examples provided above.

Competitor Comparisons

Pure Go termbox implementation

Pros of termbox-go

  • Simpler API, easier to get started for beginners
  • Lightweight with minimal dependencies
  • Good performance for basic terminal applications

Cons of termbox-go

  • Limited color support (16 colors)
  • Lacks advanced features like mouse support and true color
  • Less actively maintained compared to tcell

Code Comparison

termbox-go:

err := termbox.Init()
defer termbox.Close()

termbox.SetCell(x, y, ch, fg, bg)
termbox.Flush()

tcell:

screen, err := tcell.NewScreen()
screen.Init()
defer screen.Fini()

screen.SetContent(x, y, ch, nil, tcell.StyleDefault)
screen.Show()

Both libraries provide similar basic functionality for terminal manipulation, but tcell offers more advanced features and better maintainability. termbox-go is simpler to use and may be sufficient for basic terminal applications, while tcell is more suitable for complex projects requiring advanced terminal capabilities.

tcell has better color support, including true color, and offers additional features like mouse input handling. It also has more active development and a larger community. However, termbox-go's simplicity can be advantageous for smaller projects or developers new to terminal programming in Go.

13,161

Terminal UI library with rich, interactive widgets — written in Golang

Pros of tview

  • Higher-level abstraction, providing ready-to-use UI components
  • Easier to create complex terminal user interfaces quickly
  • Built-in support for themes and styles

Cons of tview

  • Less flexible for custom low-level terminal manipulations
  • Potentially higher memory footprint due to additional abstractions
  • May have a steeper learning curve for developers familiar with lower-level APIs

Code Comparison

tview example:

app := tview.NewApplication()
box := tview.NewBox().SetBorder(true).SetTitle("Hello, world!")
if err := app.SetRoot(box, true).Run(); err != nil {
    panic(err)
}

tcell example:

s, _ := tcell.NewScreen()
s.Init()
s.SetContent(10, 10, 'H', nil, tcell.StyleDefault)
s.Show()
for {
    ev := s.PollEvent()
    // Handle events
}

tview builds on top of tcell, providing a higher-level API for creating terminal user interfaces. While tcell offers more fine-grained control over terminal operations, tview simplifies the process of building complex UIs with pre-built components. The choice between the two depends on the specific requirements of your project and the level of abstraction you prefer.

13,461

Golang terminal dashboard

Pros of termui

  • Higher-level abstraction for building terminal UIs
  • Provides pre-built widgets and components
  • Easier to create complex layouts and dashboards

Cons of termui

  • Less flexible for custom terminal manipulation
  • Potentially higher resource usage due to abstraction layer
  • May have limitations for certain advanced use cases

Code Comparison

termui example:

ui.Init()
p := widgets.NewParagraph()
p.Text = "Hello World!"
ui.Render(p)

tcell example:

s, _ := tcell.NewScreen()
s.Init()
s.SetContent(0, 0, 'H', nil, tcell.StyleDefault)
s.Show()

Summary

termui is better suited for quickly building terminal-based user interfaces with pre-built components, while tcell provides lower-level control over terminal operations. termui offers a more straightforward approach for creating dashboards and complex layouts, but may be less flexible for custom terminal manipulations. tcell, on the other hand, gives developers finer control over terminal interactions but requires more code to achieve similar results to termui's built-in widgets.

10,432

Minimalist Go package aimed at creating Console User Interfaces.

Pros of gocui

  • Higher-level abstraction for creating text-based user interfaces
  • Built-in support for widgets like views and keybindings
  • Easier to create complex layouts and manage multiple views

Cons of gocui

  • Less flexible for low-level terminal manipulation
  • May have higher overhead for simpler applications
  • Smaller community and fewer updates compared to tcell

Code Comparison

gocui example:

g, err := gocui.NewGui(gocui.OutputNormal)
if err != nil {
    log.Panicln(err)
}
defer g.Close()

g.SetManagerFunc(layout)

tcell example:

s, err := tcell.NewScreen()
if err != nil {
    log.Fatalf("%+v", err)
}
if err := s.Init(); err != nil {
    log.Fatalf("%+v", err)
}

gocui provides a higher-level API for creating and managing views, while tcell offers more direct control over the terminal screen. gocui is better suited for complex TUI applications, whereas tcell is more appropriate for applications requiring fine-grained control over terminal output and input handling.

2,113

A UI library for terminal applications.

Pros of tui-go

  • Higher-level abstraction for building TUIs, with built-in widgets and layouts
  • Easier to create complex user interfaces with less code
  • Better suited for developers who want a quick start in building TUIs

Cons of tui-go

  • Less flexible and customizable compared to tcell's lower-level approach
  • Smaller community and fewer resources available
  • Not actively maintained (last commit in 2019)

Code Comparison

tui-go example:

box := tui.NewVBox(
    tui.NewLabel("Hello, world!"),
    tui.NewLabel("Press q to quit."),
)
ui, err := tui.New(box)
if err != nil {
    log.Fatal(err)
}

tcell example:

s, err := tcell.NewScreen()
if err != nil {
    log.Fatal(err)
}
s.Init()
s.SetContent(0, 0, 'H', nil, tcell.StyleDefault)
s.SetContent(1, 0, 'i', nil, tcell.StyleDefault)

tui-go provides a higher-level API with pre-built widgets, making it easier to create complex UIs quickly. tcell offers a lower-level API, giving more control over individual cells and allowing for more customization. tcell is actively maintained and has a larger community, while tui-go hasn't been updated since 2019. Developers should choose based on their specific needs and desired level of control over the TUI.

Terminal based dashboard.

Pros of termdash

  • Higher-level abstraction for building terminal dashboards
  • Rich set of pre-built widgets (charts, gauges, sparklines, etc.)
  • Built-in layout management system

Cons of termdash

  • More opinionated and less flexible than tcell
  • Steeper learning curve for simple use cases
  • Potentially higher resource usage due to abstraction layers

Code Comparison

termdash:

container, err := container.New(t, container.Border(linestyle.Light))
if err != nil {
    panic(err)
}
text, err := newTextWidget()
container.Update("textWidget", text)

tcell:

s, err := tcell.NewScreen()
if err != nil {
    log.Fatal(err)
}
s.Init()
s.SetStyle(tcell.StyleDefault.
    Foreground(tcell.ColorBlack).
    Background(tcell.ColorWhite))

termdash is built on top of tcell and provides a higher-level API for creating terminal user interfaces. It offers pre-built widgets and layout management, making it easier to create complex dashboards. However, this comes at the cost of flexibility and a steeper learning curve.

tcell, on the other hand, is a lower-level library that provides direct control over the terminal. It's more flexible and lightweight but requires more code to create complex interfaces. tcell is better suited for simpler applications or when you need fine-grained control over the terminal output.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Tcell

Tcell is a Go package that provides a cell based view for text terminals, like XTerm. It was inspired by termbox, but includes many additional improvements.

Stand With Ukraine Docs Linux macOS Windows Web Assembly Coverage Go Report Card Discord Latest Release

[!NOTE] This is version 3 of Tcell. There are breaking changes relative to versions 1 and 2. Version 2 remains available using the import github.com/gdamore/tcell/v2. Version 1 Version 1.x remains available using the import github.com/gdamore/tcell, but is unmaintained and should not be used.

Tutorial

A brief, and still somewhat rough, tutorial is available.

Examples

A number of example are posted up on our Gallery. That's a wiki, and please do submit updates if you have something you want to showcase.

There are also demonstration programs in the ./demos directory, as well as some in ./_demos.

More Portable

Tcell is portable to a wide variety of systems, and is pure Go, without any need for CGO. Tcell works with mainstream systems officially supported by golang.

Following the Go support policy, Tcell officially only supports the current ("stable") version of go, and the version immediately prior ("oldstable"). This policy is necessary to make sure that we can update dependencies to pick up security fixes and new features, and it allows us to adopt changes (such as library and language features) that are only supported in newer versions of Go.

Rich Unicode & non-Unicode support

Tcell includes enhanced support for Unicode, including wide characters and grapheme clusters, provided your terminal can support them.

It will also convert to and from Unicode locales, so that the program can work with UTF-8 internally, and get reasonable output in other locales. Tcell tries hard to convert to native characters on both input and output. On output Tcell even makes use of the alternate character set to facilitate drawing certain characters.

Better Keyboard Support

Tcell also has richer support for a larger number of special keys that some terminals can send. On modern terminal emulators we can also support a rich set of modifiers, and can discriminate between e.g. CTRL-I and TAB. (This does require the terminal emulator to support one of the modern keyboard protocols.)

Better Mouse Support

Tcell supports enhanced mouse tracking mode, so your application can receive regular mouse motion events, click-drag, and wheel events, if your terminal supports it.

Working With Unicode

Internally Tcell uses UTF-8, just like Go. However, Tcell understands how to convert to and from other character sets, using the capabilities of the golang.org/x/text/encoding packages. Your application must supply them, as the full set of the most common ones bloats the program by about 2 MB. If you're lazy, and want them all anyway, see the encoding sub-directory.

Wide & Combining Characters

The Put() API takes a string, which should be legal UTF-8, and displays the first grapheme cluster (which may composed of multiple runes). It returns the actual width displayed, which can be used to advance the column positiion for the next display grapheme. Alternatively, PutStr() or PutStrStyled() can be used to display a single line of text (which will be clipped at the edge of the screen).

If a second character is displayed immediately in the cell adjacent to a wide character (offset by one instead of by two), then the results are undefined.

Colors

Tcell assumes the ANSI/XTerm color palette for up to 256 colors, although terminals such as legacy ANSI terminals may only support 8 colors.

24-bit Color

Tcell supports 24-bit color! (That is, if your terminal can support it.)

There are a few ways you can enable (or disable) 24-bit color.

  • You can force this one by setting the COLORTERM environment variable to truecolor. This environment variable is frequently set by terminal emulators that support 24-bit color.

  • On Windows, 24-bit color support is assumed. (All modern Windows terminal emulators support it.)

  • If you set your TERM environment variable to a value with the suffix -truecolor or -direct, then 24-bit color compatible with XTerm and ECMA-48 will be assumed.

  • You can disable 24-bit color by setting TCELL_TRUECOLOR=disable in your environment.

When using 24-bit color, programs will display the colors that the programmer intended, overriding any "themes" the user may have set in their terminal emulator. (For some cases, accurate color fidelity is more important than respecting themes. For other cases, such as typical text apps that only use a few colors, its more desirable to respect the themes that the user has established.)

Performance

Reasonable attempts have been made to minimize sending data to terminals, avoiding repeated sequences or drawing the same cell on refresh updates.

Mouse Support

Mouse tracking, buttons, and even wheel mice are supported on most terminal emulators, as well as Windows.

Bracketed Paste

Terminals that support support it, can use bracketed paste. See EnablePaste() for details.

Breaking Changes in v3

There are a number of changes in Tcell version 3, which break compatibility with version 2 and version 1.

Your application will almost certainly need some minor updates to work with version 3.

Please see the CHANGESv3 document for a list.

Platforms

POSIX (Linux, FreeBSD, macOS, Solaris, etc.)

Everything works using pure Go on mainstream platforms. Esoteric platforms (e.g. zOS or AIX) are supported on a best-effort only basis. Pull requests to fix any issues found are welcome!

Windows

Modern Windows is supported. Please see the README-windows document for much more detailed information.

WASM

WASM is supported, but needs additional setup detailed in README-wasm.

Plan 9

Plan 9 is supported on a best-effort basis. Please see the README-plan9 document for more information.

Commercial Support

Tcell is absolutely free, but if you want to obtain commercial, professional support, there are options.

  • TideLift subscriptions include support for Tcell, as well as many other open source packages.
  • Staysail Systems Inc. offers direct support, and custom development around Tcell on an hourly basis.