Go TUIs with Bubble Tea

module example.com/shelf-tui

go 1.27

require (
	charm.land/bubbles/v2 v2.2.1
	charm.land/bubbletea/v2 v2.1.0
	charm.land/huh/v2 v2.0.3
	charm.land/lipgloss/v2 v2.0.6
	charm.land/glamour/v2 v2.0.1
)

type Model interface {
	Init() Cmd
	Update(Msg) (Model, Cmd)
	View() View
}

type loadedMsg []book
type failedMsg struct{ err error }

func loadBooks(path string) tea.Cmd {
	return func() tea.Msg {
		data, err := os.ReadFile(path)
		if err != nil {
			return failedMsg{err}
		}
		var books []book
		if err := json.Unmarshal(data, &books); err != nil {
			return failedMsg{err}
		}
		return loadedMsg(books)
	}
}

func (m model) View() tea.View {
	v := tea.NewView(m.render())
	v.AltScreen = true
	v.MouseMode = tea.MouseModeCellMotion
	v.WindowTitle = "shelf tui"
	return v
}

// list: items, delegate, initial width and height
l := list.New(nil, list.NewDefaultDelegate(), 0, 0)
l.Title = "Catalogue"
l.SetFilteringEnabled(false) // the program has its own search box
l.SetShowHelp(false)
l.SetShowStatusBar(false)
l.SetItems(items)            // []list.Item
sel, ok := l.SelectedItem().(book)

// table: columns and rows, focus decides whether it reacts to keys
t := table.New(
	table.WithColumns([]table.Column{{Title: "Title", Width: 26}, {Title: "Due", Width: 12}}),
	table.WithRows([]table.Row{{"Dune", "2026-11-02"}}),
	table.WithHeight(6),
)
t.Focus() // t.Blur() stops it reacting to key presses

// textinput: Focus returns a tea.Cmd (it starts the cursor blink)
ti := textinput.New()
ti.Placeholder = "title or author"
cmd := ti.Focus()

// viewport: width and height are options, content is a string
vp := viewport.New(viewport.WithWidth(40), viewport.WithHeight(10))
vp.SoftWrap = true
vp.SetContent(longText)

// spinner and progress
sp := spinner.New(spinner.WithSpinner(spinner.Dot))
pb := progress.New(progress.WithWidth(30))
cmd = pb.SetPercent(0.4) // returns a tea.Cmd that animates to the new value

p := paginator.New(paginator.WithPerPage(10))
p.SetTotalPages(len(books))
start, end := p.GetSliceBounds(len(books))
visible := books[start:end]
// forward key presses: p, cmd = p.Update(msg)

var (
	box = lipgloss.NewStyle().
		Border(lipgloss.RoundedBorder()).
		BorderForeground(lipgloss.Color("240"))
	activeBox = box.BorderForeground(lipgloss.Color("63"))
	title     = lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("#7D56F4"))
)

left := box.Padding(0, 1).Render(title.Render("Catalogue") + "\n" + body)
row := lipgloss.JoinHorizontal(lipgloss.Top, left, right)
screen := lipgloss.JoinVertical(lipgloss.Left, header, row, footer)

lipgloss.Println(title.Render("Overdue loans"))             // stdout, downsampled to the terminal's profile
lipgloss.Fprintln(os.Stderr, warn.Render("shelfd offline")) // stderr

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

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	switch msg := msg.(type) {
	case tea.BackgroundColorMsg:
		m.styles = newStyles(msg.IsDark())
	}
	return m, nil
}

func newStyles(isDark bool) styles {
	pick := lipgloss.LightDark(isDark)
	return styles{
		title: lipgloss.NewStyle().Foreground(pick(lipgloss.Color("#333333"), lipgloss.Color("#f1f1f1"))),
	}
}

[
  {"title": "Dune", "author": "Frank Herbert", "isbn": "9780441013593",
   "notes": "A desert planet, a spice, and a long political game.", "loan": "ana", "due": "2026-11-02"},
  {"title": "The Left Hand of Darkness", "author": "Ursula K. Le Guin", "isbn": "9780441478125",
   "notes": "On Gethen the people have no fixed sex; an envoy has to learn what that means for politics."},
  {"title": "A Canticle for Leibowitz", "author": "Walter M. Miller Jr.", "isbn": "9780060892999",
   "notes": "Monks preserve fragments of a lost technological age.", "loan": "ben", "due": "2026-11-09"},
  {"title": "The Dispossessed", "author": "Ursula K. Le Guin", "isbn": "9780061054884",
   "notes": "Two worlds, one anarchist and one capitalist, and a physicist who belongs to neither."}
]

package main

import (
	"encoding/json"
	"fmt"
	"os"
	"strings"
	"unicode"

	"charm.land/bubbles/v2/list"
	"charm.land/bubbles/v2/spinner"
	"charm.land/bubbles/v2/table"
	"charm.land/bubbles/v2/textinput"
	"charm.land/bubbles/v2/viewport"
	tea "charm.land/bubbletea/v2"
	"charm.land/lipgloss/v2"
)

// ---- data -----------------------------------------------------------------

type book struct {
	Name   string `json:"title"`
	Author string `json:"author"`
	ISBN   string `json:"isbn"`
	Notes  string `json:"notes"`
	Loan   string `json:"loan,omitempty"`
	Due    string `json:"due,omitempty"`
}

// clean drops control characters, so a hostile title cannot inject escape sequences.
func clean(s string) string {
	return strings.Map(func(r rune) rune {
		if unicode.IsControl(r) && r != '\n' {
			return -1
		}
		return r
	}, s)
}

// book implements list.DefaultItem.
func (b book) Title() string       { return clean(b.Name) }
func (b book) Description() string { return clean(b.Author) + " - " + b.ISBN }
func (b book) FilterValue() string { return b.Name + " " + b.Author }

// ---- messages and commands --------------------------------------------------

type loadedMsg []book
type failedMsg struct{ err error }

func loadBooks(path string) tea.Cmd {
	return func() tea.Msg {
		data, err := os.ReadFile(path)
		if err != nil {
			return failedMsg{err}
		}
		var books []book
		if err := json.Unmarshal(data, &books); err != nil {
			return failedMsg{err}
		}
		return loadedMsg(books)
	}
}

// ---- model ------------------------------------------------------------------

type pane int

const (
	paneCatalogue pane = iota
	paneSearch
	paneLoans
)

type model struct {
	path    string
	all     []book
	list    list.Model
	search  textinput.Model
	loans   table.Model
	detail  viewport.Model
	spin    spinner.Model
	focus   pane
	loading bool
	err     error

	width, height int
}

var (
	box       = lipgloss.NewStyle().Border(lipgloss.RoundedBorder()).BorderForeground(lipgloss.Color("240"))
	activeBox = box.BorderForeground(lipgloss.Color("63"))
	helpStyle = lipgloss.NewStyle().Foreground(lipgloss.Color("241"))
)

func newModel(path string) model {
	l := list.New(nil, list.NewDefaultDelegate(), 0, 0)
	l.Title = "Catalogue"
	l.SetFilteringEnabled(false)
	l.SetShowHelp(false)
	l.SetShowStatusBar(false)

	ti := textinput.New()
	ti.Prompt = "/ "
	ti.Placeholder = "search title or author"

	cols := []table.Column{{Title: "Title", Width: 26}, {Title: "Borrower", Width: 14}, {Title: "Due", Width: 12}}
	t := table.New(table.WithColumns(cols), table.WithHeight(6))

	vp := viewport.New(viewport.WithWidth(30), viewport.WithHeight(10))
	vp.SoftWrap = true

	return model{
		path:    path,
		list:    l,
		search:  ti,
		loans:   t,
		detail:  vp,
		spin:    spinner.New(spinner.WithSpinner(spinner.Dot)),
		loading: true,
	}
}

func (m model) Init() tea.Cmd {
	return tea.Batch(m.spin.Tick, loadBooks(m.path))
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	switch msg := msg.(type) {
	case tea.WindowSizeMsg:
		m.width, m.height = msg.Width, msg.Height
		m.layout()
		return m, nil

	case spinner.TickMsg:
		if !m.loading {
			return m, nil // stop the animation by not returning another tick
		}
		var cmd tea.Cmd
		m.spin, cmd = m.spin.Update(msg)
		return m, cmd

	case loadedMsg:
		m.loading = false
		m.all = []book(msg)
		m.applyFilter()
		return m, nil

	case failedMsg:
		m.loading = false
		m.err = msg.err
		return m, nil

	case tea.MouseWheelMsg:
		var cmd tea.Cmd
		m.detail, cmd = m.detail.Update(msg)
		return m, cmd

	case tea.KeyPressMsg:
		return m.handleKey(msg)
	}
	return m, nil
}

func (m model) handleKey(msg tea.KeyPressMsg) (tea.Model, tea.Cmd) {
	key := msg.String()
	if key == "ctrl+c" {
		return m, tea.Quit
	}

	// While the search box has focus, it gets every key except the two that leave it.
	if m.focus == paneSearch {
		if key == "enter" || key == "esc" {
			m.focus = paneCatalogue
			m.search.Blur()
			return m, nil
		}
		var cmd tea.Cmd
		m.search, cmd = m.search.Update(msg)
		m.applyFilter()
		return m, cmd
	}

	switch key {
	case "q":
		return m, tea.Quit
	case "/":
		m.focus = paneSearch
		return m, m.search.Focus()
	case "tab":
		if m.focus == paneCatalogue {
			m.focus = paneLoans
			m.loans.Focus()
		} else {
			m.focus = paneCatalogue
			m.loans.Blur()
		}
		return m, nil
	case "pgdown":
		m.detail.ScrollDown(5)
		return m, nil
	case "pgup":
		m.detail.ScrollUp(5)
		return m, nil
	}

	var cmd tea.Cmd
	if m.focus == paneLoans {
		m.loans, cmd = m.loans.Update(msg)
	} else {
		m.list, cmd = m.list.Update(msg)
		m.showSelected()
	}
	return m, cmd
}

// applyFilter rebuilds the list and the loans table from m.all and the search text.
func (m *model) applyFilter() {
	q := strings.ToLower(strings.TrimSpace(m.search.Value()))
	var items []list.Item
	var rows []table.Row
	for _, b := range m.all {
		if q == "" || strings.Contains(strings.ToLower(b.FilterValue()), q) {
			items = append(items, b)
		}
		if b.Loan != "" {
			rows = append(rows, table.Row{clean(b.Name), clean(b.Loan), b.Due})
		}
	}
	m.list.SetItems(items)
	m.loans.SetRows(rows)
	m.showSelected()
}

func (m *model) showSelected() {
	b, ok := m.list.SelectedItem().(book)
	if !ok {
		m.detail.SetContent("No book selected.")
		return
	}
	var sb strings.Builder
	fmt.Fprintf(&sb, "%s\n%s\nISBN %s\n\n%s\n", clean(b.Name), clean(b.Author), b.ISBN, clean(b.Notes))
	if b.Loan != "" {
		fmt.Fprintf(&sb, "\nOn loan to %s until %s\n", clean(b.Loan), b.Due)
	}
	m.detail.SetContent(sb.String())
	m.detail.GotoTop()
}

// layout sizes the components. The panes get a one-cell border on each side.
func (m *model) layout() {
	if m.width < 40 || m.height < 16 {
		return
	}
	leftW := m.width / 2
	rightW := m.width - leftW
	midH := m.height - 10 // search line + loans pane (8) + help line

	m.list.SetSize(leftW-2, midH-2)
	m.detail.SetWidth(rightW - 4) // border (2) and padding (2)
	m.detail.SetHeight(midH - 2)
	m.loans.SetWidth(m.width - 2)
	m.loans.SetHeight(6)
	m.search.SetWidth(m.width - 4)
}

func (m model) View() tea.View {
	var body string
	switch {
	case m.err != nil:
		body = "error: " + clean(m.err.Error()) + "\n"
	case m.loading:
		body = m.spin.View() + " loading " + m.path + "\n"
	case m.width < 40 || m.height < 16:
		body = "terminal too small (needs 40x16)\n"
	default:
		body = m.render()
	}
	v := tea.NewView(body)
	v.AltScreen = true
	v.MouseMode = tea.MouseModeCellMotion
	v.WindowTitle = "shelf tui"
	return v
}

func (m model) render() string {
	cat, loans := box, box
	switch m.focus {
	case paneCatalogue:
		cat = activeBox
	case paneLoans:
		loans = activeBox
	}
	left := cat.Render(m.list.View())
	right := box.Padding(0, 1).Render(m.detail.View())
	middle := lipgloss.JoinHorizontal(lipgloss.Top, left, right)
	bottom := loans.Render(m.loans.View())
	help := helpStyle.Render("/ search   tab loans   pgup/pgdn scroll   q quit")
	return lipgloss.JoinVertical(lipgloss.Left, m.search.View(), middle, bottom, help)
}

func main() {
	path := "books.json"
	if len(os.Args) > 1 {
		path = os.Args[1]
	}
	if _, err := tea.NewProgram(newModel(path)).Run(); err != nil {
		fmt.Fprintln(os.Stderr, "shelf:", err)
		os.Exit(1)
	}
}

package main

import (
	"errors"
	"fmt"
	"os"
	"strings"

	"charm.land/huh/v2"
)

func validISBN(s string) error {
	digits := strings.NewReplacer("-", "", " ", "").Replace(s)
	if len(digits) != 10 && len(digits) != 13 {
		return errors.New("an ISBN has 10 or 13 digits")
	}
	return nil
}

func main() {
	var title, author, isbn, section string
	var confirm bool

	form := huh.NewForm(
		huh.NewGroup(
			huh.NewInput().Title("Title").Value(&title).
				Validate(func(s string) error {
					if strings.TrimSpace(s) == "" {
						return errors.New("the title is required")
					}
					return nil
				}),
			huh.NewInput().Title("Author").Value(&author),
			huh.NewInput().Title("ISBN").Value(&isbn).Validate(validISBN),
		),
		huh.NewGroup(
			huh.NewSelect[string]().
				Title("Section").
				Options(huh.NewOptions("fiction", "science", "history")...).
				Value(&section),
			huh.NewConfirm().Title("Add this book?").Value(&confirm),
		),
	).WithAccessible(os.Getenv("ACCESSIBLE") != "")

	if err := form.Run(); err != nil {
		if errors.Is(err, huh.ErrUserAborted) {
			fmt.Fprintln(os.Stderr, "cancelled")
			os.Exit(130) // the shell convention for "interrupted"
		}
		fmt.Fprintln(os.Stderr, "shelf:", err)
		os.Exit(1)
	}
	if confirm {
		fmt.Printf("added %q by %s (%s) to %s\n", title, author, isbn, section)
	}
}

package main

import (
	"fmt"
	"os"

	"charm.land/glamour/v2"
	"charm.land/lipgloss/v2"
)

func main() {
	notes := "# Dune\n\nA desert planet, a spice, and a long political game.\n\n- **Author:** Frank Herbert\n- **Shelf:** fiction\n"

	out, err := glamour.Render(notes, "dark")
	if err != nil {
		fmt.Fprintln(os.Stderr, "shelf:", err)
		os.Exit(1)
	}
	lipgloss.Print(out) // Glamour does not downsample colours; Lip Gloss does

	r, err := glamour.NewTermRenderer(glamour.WithWordWrap(60))
	if err == nil {
		if wrapped, err := r.Render(notes); err == nil {
			lipgloss.Print(wrapped)
		}
	}
}

package main

import (
	"testing"

	tea "charm.land/bubbletea/v2"
)

func key(s string) tea.KeyPressMsg {
	r := []rune(s)[0]
	return tea.KeyPressMsg{Code: r, Text: s}
}

func TestSearchFiltersCatalogue(t *testing.T) {
	var m tea.Model = newModel("books.json")
	m, _ = m.Update(tea.WindowSizeMsg{Width: 100, Height: 30})
	m, _ = m.Update(loadedMsg{
		{Name: "Dune", Author: "Frank Herbert", ISBN: "9780441013593"},
		{Name: "The Dispossessed", Author: "Ursula K. Le Guin", ISBN: "9780061054884"},
	})
	if n := len(m.(model).list.Items()); n != 2 {
		t.Fatalf("expected 2 books, got %d", n)
	}

	for _, s := range []string{"/", "d", "u", "n", "e"} {
		m, _ = m.Update(key(s))
	}
	if n := len(m.(model).list.Items()); n != 1 {
		t.Fatalf("expected 1 book after searching for dune, got %d", n)
	}
}

import (
	"bytes"
	"testing"
	"time"

	tea "charm.land/bubbletea/v2"
	"github.com/charmbracelet/x/exp/teatest/v2"
)

func TestProgramQuits(t *testing.T) {
	tm := teatest.NewTestModel(t, newModel("testdata/books.json"), teatest.WithInitialTermSize(100, 30))

	teatest.WaitFor(t, tm.Output(), func(out []byte) bool {
		return bytes.Contains(out, []byte("Dune"))
	}, teatest.WithDuration(3*time.Second))

	tm.Send(tea.KeyPressMsg{Code: 'q', Text: "q"})
	tm.WaitFinished(t, teatest.WithFinalTimeout(2*time.Second))
}

Output shelf-tui.gif
Output shelf-tui.txt

Require go

Set Shell "bash"
Set FontSize 18
Set Width 1200
Set Height 700

Type "go run . books.json"
Enter
Sleep 2s

Type "/"
Type "dune"
Sleep 1s
Enter

Down
Sleep 500ms
Tab
Sleep 500ms
Type "q"
Sleep 500ms