README

Bubble Tea


    
    
    
    


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


    


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 high-performance cell-based renderer, built-in color downsampling,
declarative views, high-fidelity keyboard and mouse handling, native clipboard
support, and more.

To get started, see the tutorial below, the [examples][examples], the
[docs][docs], and some common resources.

 [!TIP]

 Upgrading from v1? Check out the upgrade guide, or
 point your LLM at it and let it go to town.

 By the way

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


      
    


---

 Tutorial

Bubble Tea is based on the functional design paradigms of [The Elm
Architecture][elm], 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][tut-source].

[elm]: https://guide.elm-lang.org/architecture/
[tut-source]: https://github.com/charmbracelet/bubbletea/tree/main/tutorials/basics

 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.

go
package main

// These imports will be used later in the tutorial. If you save the file
// now, Go might complain they are unused, but that's fine.
// You may also need to run go mod tidy to download bubbletea and its
// dependencies.
import (
    "fmt"
    "os"

    tea "charm.land/bubbletea/v2"
)


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.

go
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. 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.”

go
func initialModel() model {
	return model{
		// Our to-do li

Top issues

Discussions

Latest release

Terminal size query vulnerability

This patch version fixes a vulnerability reported by @Reload3d. You can find the details of the exploit here.

Best regards,
Charm XX 💫

 Changelog
 Fixed
 9c6c325f83348ee7215fb7a7aca3bc6316217056: fix: ingnore implausible terminal resize reports (1887) (@andrinoff)
 Other stuff
 67b4c7a8a2b34a0b1ce15261b0c705bc7e1a04b7: v2.1.1 (@andrinoff)

---



Thoughts? Questions? We love hearing from you. Feel free to reach out on X, Discord, Slack, The Fediverse, Bluesky.