Bubble Tea: fun, functional and stateful way to build terminal apps

Bubble Tea: fun, functional and stateful way to build terminal apps

I be wild about add-ons, because they are astonishing.

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 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 and some common resources.

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


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

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

This tutorial assumes you have a working knowledge of Go.

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 (

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
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 shopping 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 {

// The “down” and “j” keys move the cursor down
case “down”, “j”:
if m.cursor func (m model) View() string {
// The header
s :=”What should we buy at the market?nn”

// 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] %sn”, 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:

Read More
Share this on knowasiak.com to discuss with people on this topicSign up on Knowasiak.com now if you’re not registered yet.

Charlie Layers

Charlie Layers

Fill your life with experiences so you always have a great story to tell

Leave a Reply