bubbletea

A powerful little TUI framework 🏗

27,461

792

27,461

121

View on GitHub

Top Related Projects

tview

10,905

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

tcell

4,560

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

gocui

9,886

Minimalist Go package aimed at creating Console User Interfaces.

promptui

6,055

Interactive prompt for command-line applications

Quick Overview

Bubbletea is a powerful and flexible framework for building terminal user interfaces (TUIs) in Go. It provides a composable model-view-update (MVU) architecture, making it easy to create interactive and dynamic terminal applications with minimal boilerplate code.

Pros

Easy to learn and use, especially for developers familiar with functional programming concepts
Highly composable architecture allows for building complex UIs from simple components
Excellent performance and low resource usage
Active community and regular updates

Cons

Steeper learning curve for developers not familiar with functional programming paradigms
Limited built-in UI components compared to some other TUI libraries
Documentation could be more comprehensive for advanced use cases
Debugging can be challenging due to the nature of terminal applications

Code Examples

Creating a simple counter:

package main

import (
    "fmt"
    tea "github.com/charmbracelet/bubbletea"
)

type model struct {
    count int
}

func (m model) Init() tea.Cmd {
    return nil
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyMsg:
        switch msg.String() {
        case "q", "ctrl+c":
            return m, tea.Quit
        case "+":
            m.count++
        case "-":
            m.count--
        }
    }
    return m, nil
}

func (m model) View() string {
    return fmt.Sprintf("Count: %d\n\n(+) increment\n(-) decrement\n(q) quit", m.count)
}

func main() {
    p := tea.NewProgram(model{})
    if _, err := p.Run(); err != nil {
        fmt.Printf("Alas, there's been an error: %v", err)
        os.Exit(1)
    }
}

Creating a simple text input:

package main

import (
    "fmt"
    tea "github.com/charmbracelet/bubbletea"
    "github.com/charmbracelet/bubbles/textinput"
)

type model struct {
    textInput textinput.Model
}

func initialModel() model {
    ti := textinput.New()
    ti.Placeholder = "Type something..."
    ti.Focus()
    return model{
        textInput: ti,
    }
}

func (m model) Init() tea.Cmd {
    return textinput.Blink
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    var cmd tea.Cmd
    switch msg := msg.(type) {
    case tea.KeyMsg:
        switch msg.Type {
        case tea.KeyCtrlC, tea.KeyEsc:
            return m, tea.Quit
        }
    }
    m.textInput, cmd = m.textInput.Update(msg)
    return m, cmd
}

func (m model) View() string {
    return fmt.Sprintf(
        "What's your name?\n\n%s\n\n(esc to quit)",
        m.textInput.View(),
    )
}

func main() {
    p := tea.NewProgram(initialModel())
    if _, err := p.Run(); err != nil {
        fmt.Printf("Alas, there's been an error: %v", err)
        os.Exit(1)
    }
}

Getting Started

To get started with Bubbletea, first install it using Go modules:

go get github.com/charmbracelet/bubbletea

Then, create a new Go file and import the library:

package main

import (
    "fmt"
    tea "github.com/charmbracelet/bubbletea"
)

func main() {
    p := tea.NewProgram(initialModel())
    if _, err := p.Run(); err != nil {
        fmt.Printf("Alas, there's been an error: %

Competitor Comparisons

tview

10,905

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

Pros of tview

More traditional widget-based approach, familiar to developers used to GUI frameworks
Extensive set of pre-built widgets for common UI elements
Simpler learning curve for developers new to TUI development

Cons of tview

Less flexible for creating custom, non-standard UI layouts
May be more challenging to create highly dynamic or animated interfaces
Slightly more verbose code for simple applications

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)
}

Bubbletea example:

type model struct{}
func (m model) Init() tea.Cmd { return nil }
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) { return m, nil }
func (m model) View() string { return "Hello, world!" }
if err := tea.NewProgram(model{}).Start(); err != nil {
    panic(err)
}

Both libraries offer powerful tools for creating terminal user interfaces in Go. tview provides a more traditional widget-based approach with a rich set of pre-built components, making it easier for developers familiar with GUI frameworks. Bubbletea, on the other hand, offers a more flexible and functional approach, allowing for greater customization and potentially more concise code for complex applications.

tcell

4,560

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

Pros of tcell

Lower-level library offering more fine-grained control over terminal operations
Wider platform support, including Windows
More mature and established project with a longer history

Cons of tcell

Steeper learning curve due to its lower-level nature
Requires more boilerplate code to create interactive terminal applications
Less opinionated, which may lead to more decision-making for developers

Code Comparison

tcell:

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

screen.SetContent(0, 0, 'H', nil, tcell.StyleDefault)
screen.Show()

Bubbletea:

p := tea.NewProgram(initialModel())
if _, err := p.Run(); err != nil {
    fmt.Printf("Alas, there's been an error: %v", err)
    os.Exit(1)
}

Summary

tcell is a lower-level terminal library offering more control and wider platform support, but with a steeper learning curve. Bubbletea, built on top of tcell, provides a higher-level, more opinionated framework for building terminal user interfaces with less boilerplate code. The choice between the two depends on the specific needs of the project and the developer's preferences for control versus convenience.

gocui

9,886

Minimalist Go package aimed at creating Console User Interfaces.

Pros of gocui

Simpler API, easier to get started for basic TUI applications
More focused on traditional ncurses-style interfaces
Better suited for applications with static layouts

Cons of gocui

Less flexible for dynamic or complex UIs
Fewer built-in widgets and components
Less active development and community support

Code Comparison

gocui example:

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

g.SetManagerFunc(layout)

Bubbletea example:

p := tea.NewProgram(initialModel())
if err := p.Start(); err != nil {
    fmt.Printf("Alas, there's been an error: %v", err)
    os.Exit(1)
}

gocui focuses on creating and managing views within a predefined layout, while Bubbletea uses a more component-based approach with a central update loop. Bubbletea's model is more flexible for complex, dynamic UIs, but gocui may be simpler for basic, static layouts.

termui

13,182

Golang terminal dashboard

Pros of termui

More comprehensive set of pre-built UI components
Easier to create complex layouts with grid system
Better suited for data visualization with built-in charts and graphs

Cons of termui

Less flexible and customizable than Bubbletea
Steeper learning curve for beginners
Less active development and community support

Code Comparison

termui example:

ui.NewPar("Hello World!")
ui.NewGauge()
ui.NewBarChart()

Bubbletea example:

m := model{choices: []string{"Tea", "Coffee"}}
p := tea.NewProgram(m)
p.Start()

Summary

termui offers a rich set of pre-built components and is well-suited for data-heavy applications, while Bubbletea provides a more flexible and customizable approach to building terminal user interfaces. termui's grid system makes complex layouts easier, but Bubbletea's simpler model may be more approachable for beginners. Bubbletea has a more active community and ongoing development, which could be beneficial for long-term project support.

promptui

6,055

Interactive prompt for command-line applications

Pros of promptui

Simpler API, easier to get started for basic CLI prompts
Focused specifically on prompts, making it more lightweight
Better suited for traditional CLI applications with linear flow

Cons of promptui

Less flexible for complex, interactive TUI applications
Limited styling options compared to Bubbletea's rich theming capabilities
Lacks support for more advanced features like custom widgets or layouts

Code Comparison

promptui example:

prompt := promptui.Select{
    Label: "Select Day",
    Items: []string{"Monday", "Tuesday", "Wednesday", "Thursday", "Friday"},
}
_, result, err := prompt.Run()

Bubbletea example:

type model struct {
    choices  []string
    cursor   int
    selected string
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyMsg:
        // Handle key presses
    }
    return m, nil
}

Bubbletea offers more flexibility and control over the application's state and behavior, while promptui provides a simpler interface for basic prompts. Bubbletea is better suited for complex, interactive TUI applications, while promptui excels in straightforward CLI prompts and input gathering.

Convert designs to code with AI

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

Try Visual Copilot

README

Bubble Tea

The fun, functional and stateful way to build terminal apps. A Go framework based on The Elm Architecture. Bubble Tea is well-suited for simple and complex terminal applications, either inline, full-window, or a mix of both.

Bubble Tea Example

Bubble Tea is in use in production and includes a number of features and performance optimizations weâve added along the way. Among those is a standard framerate-based renderer, a renderer for high-performance scrollable regions which works alongside the main renderer, and mouse support.

To get started, see the tutorial below, the examples, the docs, the video tutorials and some common resources.

By the way

Be sure to check out Bubbles, a library of common UI components for Bubble Tea.

Tutorial

Bubble Tea is based on the functional design paradigms of The Elm Architecture, which happens to work nicely with Go. It's a delightful way to build applications.

This tutorial assumes you have a working knowledge of Go.

By the way, the non-annotated source code for this program is available on GitHub.

Enough! Let's get to it.

For this tutorial, we're making a shopping list.

To start we'll define our package and import some libraries. Our only external import will be the Bubble Tea library, which we'll call tea for short.

package main

import (
    "fmt"
    "os"

    tea "github.com/charmbracelet/bubbletea"
)

Bubble Tea programs are comprised of a model that describes the application state and three simple methods on that model:

Init, a function that returns an initial command for the application to run.
Update, a function that handles incoming events and updates the model accordingly.
View, a function that renders the UI based on the data in the model.

The Model

So let's start by defining our model which will store our application's state. It can be any type, but a struct usually makes the most sense.

type model struct {
    choices  []string           // items on the to-do list
    cursor   int                // which to-do list item our cursor is pointing at
    selected map[int]struct{}   // which to-do items are selected
}

Initialization

Next, weâll define our applicationâs initial state. In this case, weâre defining a function to return our initial model, however, we could just as easily define the initial model as a variable elsewhere, too.

func initialModel() model {
	return model{
		// Our to-do list is a grocery list
		choices:  []string{"Buy carrots", "Buy celery", "Buy kohlrabi"},

		// A map which indicates which choices are selected. We're using
		// the  map like a mathematical set. The keys refer to the indexes
		// of the `choices` slice, above.
		selected: make(map[int]struct{}),
	}
}

Next, we define the Init method. Init can return a Cmd that could perform some initial I/O. For now, we don't need to do any I/O, so for the command, we'll just return nil, which translates to "no command."

func (m model) Init() tea.Cmd {
    // Just return `nil`, which means "no I/O right now, please."
    return nil
}

The Update Method

Next up is the update method. The update function is called when âthings happen.â Its job is to look at what has happened and return an updated model in response. It can also return a Cmd to make more things happen, but for now don't worry about that part.

In our case, when a user presses the down arrow, Updateâs job is to notice that the down arrow was pressed and move the cursor accordingly (or not).

The âsomething happenedâ comes in the form of a Msg, which can be any type. Messages are the result of some I/O that took place, such as a keypress, timer tick, or a response from a server.

We usually figure out which type of Msg we received with a type switch, but you could also use a type assertion.

For now, we'll just deal with tea.KeyMsg messages, which are automatically sent to the update function when keys are pressed.

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {

    // Is it a key press?
    case tea.KeyMsg:

        // Cool, what was the actual key pressed?
        switch msg.String() {

        // These keys should exit the program.
        case "ctrl+c", "q":
            return m, tea.Quit

        // The "up" and "k" keys move the cursor up
        case "up", "k":
            if m.cursor > 0 {
                m.cursor--
            }

        // The "down" and "j" keys move the cursor down
        case "down", "j":
            if m.cursor < len(m.choices)-1 {
                m.cursor++
            }

        // The "enter" key and the spacebar (a literal space) toggle
        // the selected state for the item that the cursor is pointing at.
        case "enter", " ":
            _, ok := m.selected[m.cursor]
            if ok {
                delete(m.selected, m.cursor)
            } else {
                m.selected[m.cursor] = struct{}{}
            }
        }
    }

    // Return the updated model to the Bubble Tea runtime for processing.
    // Note that we're not returning a command.
    return m, nil
}

You may have noticed that ctrl+c and q above return a tea.Quit command with the model. Thatâs a special command which instructs the Bubble Tea runtime to quit, exiting the program.

The View Method

At last, itâs time to render our UI. Of all the methods, the view is the simplest. We look at the model in its current state and use it to return a string. That string is our UI!

Because the view describes the entire UI of your application, you donât have to worry about redrawing logic and stuff like that. Bubble Tea takes care of it for you.

func (m model) View() string {
    // The header
    s := "What should we buy at the market?\n\n"

    // Iterate over our choices
    for i, choice := range m.choices {

        // Is the cursor pointing at this choice?
        cursor := " " // no cursor
        if m.cursor == i {
            cursor = ">" // cursor!
        }

        // Is this choice selected?
        checked := " " // not selected
        if _, ok := m.selected[i]; ok {
            checked = "x" // selected!
        }

        // Render the row
        s += fmt.Sprintf("%s [%s] %s\n", cursor, checked, choice)
    }

    // The footer
    s += "\nPress q to quit.\n"

    // Send the UI for rendering
    return s
}

All Together Now

The last step is to simply run our program. We pass our initial model to tea.NewProgram and let it rip:

func main() {
    p := tea.NewProgram(initialModel())
    if _, err := p.Run(); err != nil {
        fmt.Printf("Alas, there's been an error: %v", err)
        os.Exit(1)
    }
}

Whatâs Next?

This tutorial covers the basics of building an interactive terminal UI, but in the real world you'll also need to perform I/O. To learn about that have a look at the Command Tutorial. It's pretty simple.

There are also several Bubble Tea examples available and, of course, there are Go Docs.

Debugging

Debugging with Delve

Since Bubble Tea apps assume control of stdin and stdout, youâll need to run delve in headless mode and then connect to it:

# Start the debugger
$ dlv debug --headless --api-version=2 --listen=127.0.0.1:43000 .
API server listening at: 127.0.0.1:43000

# Connect to it from another terminal
$ dlv connect 127.0.0.1:43000

If you do not explicitly supply the --listen flag, the port used will vary per run, so passing this in makes the debugger easier to use from a script or your IDE of choice.

Additionally, we pass in --api-version=2 because delve defaults to version 1 for backwards compatibility reasons. However, delve recommends using version 2 for all new development and some clients may no longer work with version 1. For more information, see the Delve documentation.

Logging Stuff

You canât really log to stdout with Bubble Tea because your TUI is busy occupying that! You can, however, log to a file by including something like the following prior to starting your Bubble Tea program:

if len(os.Getenv("DEBUG")) > 0 {
	f, err := tea.LogToFile("debug.log", "debug")
	if err != nil {
		fmt.Println("fatal:", err)
		os.Exit(1)
	}
	defer f.Close()
}

To see whatâs being logged in real time, run tail -f debug.log while you run your program in another window.

Libraries we use with Bubble Tea

Bubbles: Common Bubble Tea components such as text inputs, viewports, spinners and so on
Lip Gloss: Style, format and layout tools for terminal applications
Harmonica: A spring animation library for smooth, natural motion
BubbleZone: Easy mouse event tracking for Bubble Tea components
ntcharts: A terminal charting library built for Bubble Tea and Lip Gloss
Termenv: Advanced ANSI styling for terminal applications
Reflow: Advanced ANSI-aware methods for working with text

Bubble Tea in the Wild

For some Bubble Tea programs in production, see:

ASCII Movie: a Star Wars ASCII art movie player
AT CLI: execute AT Commands via serial port connections
Aztify: bring Microsoft Azure resources under Terraform
brows: a GitHub release browser
Canard: an RSS client
charm: the official Charm user account manager
chatgpt-cli: a CLI for ChatGPT
chatgpt-tui: a TUI for ChatGPT with SQLite sessions
ChatGPTUI: a TUI for ChatGPT
chezmoi: securely manage your dotfiles across multiple machines
chip-8: a CHIP-8 interpreter
chtop: monitor your ClickHouse node without leaving the terminal
circumflex: read Hacker News in the terminal
clidle: a Wordle clone
cLive: automate terminal operations and view them live in a browser
container-canary: a container validator
countdown: a multi-event countdown timer
CRT: a simple terminal emulator for running Bubble Tea in a dedicated window, with optional shaders
cueitup: inspect messages in an AWS SQS queue in a simple and deliberate manner
Daytona: an development environment manager
dns53: dynamic DNS with Amazon Route53; expose your EC2 quickly, securely and privately
eks-node-viewer: a tool for visualizing dynamic node usage within an EKS cluster
End Of Eden: a "Slay the Spire"-like, roguelike deck-builder game
enola: find social media accounts by username across social networks
flapioca: Flappy Bird on the CLI!
fm: a terminal-based file manager
fork-cleaner: clean up old and inactive forks in your GitHub account
fractals-cli: a multiplatform terminal fractal explorer
fztea: a Flipper Zero TUI
gama: manage GitHub Actions from the terminal
gambit: chess in the terminal
gembro: a mouse-driven Gemini browser
gh-b: a GitHub CLI extension for managing branches
gh-dash: a GitHub CLI extension for PRs and issues
gitflow-toolkit: a GitFlow submission tool
Glow: a markdown reader, browser, and online markdown stash
go-sweep: Minesweeper in the terminal
gocovsh: explore Go coverage reports from the CLI
got: a simple translator and text-to-speech app built on simplytranslate's APIs
gum: interactivity and styling for shells and shell scripts
hiSHtory: your shell history in context: synced, and queryable
httpit: a rapid http(s) benchmark tool
Huh?: an interactive prompt and form toolkit
IDNT: a batch software uninstaller
json-log-viewer: an interactive JSON log viewer
kboard: a typing game
kplay: inspect messages in a Kafka topic
laboon: a Docker-desktop-style container manager
mc: the official MinIO client
mergestat: run SQL queries on git repositories
meteor: a highly customizable conventional commit message tool
mods: AI on the CLI, built for pipelines
nachrichten: access up-to-date news in German provided by the Tagesschau
Neon Modem Overdrive: a BBS-style TUI client for Discourse, Lemmy, Lobste.rs and Hacker News
nom: an RSS reader and manager
Noted: a note viewer and manager
outtasync: identify CloudFormation stacks that are out of sync with their template files
pathos: a PATH environment variable editor
Plandex: a terminal-based AI coding engine for complex tasks
portal: secure transfers between computers
prs: stay up to date with your PRs
puffin: a TUI for hledger to manage your finances
pug: terraform task manager
punchout: takes the suck out of logging time on JIRA
redis-viewer: a Redis database browser
redis_tui: a Redis database browser
schemas: lets you inspect postgres schemas in the terminal
scrabbler: an automatic draw tool for your duplicate Scrabble games
sku: Sudoku on the CLI
Slides: a markdown-based presentation tool
SlurmCommander: a Slurm workload manager
Soft Serve: a command-line-first Git server that runs a TUI over SSH
solitaire-tui: Klondike Solitaire for the terminal
StormForge Optimize Controller: a tool for experimenting with application configurations in Kubernetes
Storydb: an improved bash/zsh-style ctrl+r command history finder
STTG: a teletext client for SVT, Swedenâs national public television station
sttr: a general-purpose text transformer
superfile a fancy, modern terminal-based file manager
tasktimer: a dead-simple task timer
termdbms: a keyboard and mouse driven database browser
tgpt: conversational AI for the CLI; no API keys necessary
ticker: a terminal stock viewer and stock position tracker
trainer: a Go concurrency coding interview simulator with learning materials
tran: securely transfer stuff between computers (based on portal)
Trufflehog: find leaked credentials
Typer: a typing test
typioca: a typing test
tz: a scheduling aid for people in multiple time zones
ugm: a unix user and group browser
walk: a terminal navigator
wander: a HashiCorp Nomad terminal client
WG Commander: a TUI for a simple WireGuard VPN setup
wishlist: an SSH directory

Feedback

We'd love to hear your thoughts on this project. Feel free to drop us a note!

Acknowledgments

Bubble Tea is based on the paradigms of The Elm Architecture by Evan Czaplicki et alia and the excellent go-tea by TJ Holowaychuk. Itâs inspired by the many great Zeichenorientierte Benutzerschnittstellen of days past.

License

MIT

Part of Charm.

Top Related Projects

Convert designs to code with AI

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

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Code Examples

Getting Started

Competitor Comparisons

Pros of tview

Cons of tview

Code Comparison

Pros of tcell

Cons of tcell

Code Comparison

Summary

Pros of gocui

Cons of gocui

Code Comparison

Pros of termui

Cons of termui

Code Comparison

Summary

Pros of promptui

Cons of promptui

Code Comparison

Convert designs to code with AI

README

Bubble Tea

By the way

Tutorial

Enough! Let's get to it.

The Model

Initialization

The Update Method

The View Method

All Together Now

Whatâs Next?

Debugging

Debugging with Delve

Logging Stuff

Libraries we use with Bubble Tea

Bubble Tea in the Wild

Feedback

Acknowledgments

License

Top Related Projects

Convert designs to code with AI

Whatâs Next?