0
# Bubble Tea
1
2
Bubble Tea is a powerful Go framework for building rich, interactive terminal user interfaces using functional programming paradigms based on The Elm Architecture. The library provides a comprehensive event-driven system where applications are built around three core concepts: a Model that represents application state, an Update function that handles incoming events and state changes, and a View function that renders the UI.
3
4
## Package Information
5
6
- **Package Name**: bubbletea
7
- **Package Type**: go module
8
- **Language**: Go
9
- **Installation**: `go get github.com/charmbracelet/bubbletea`
10
- **Go Version**: Requires Go 1.24.0+
11
- **Import Path**: `github.com/charmbracelet/bubbletea`
12
13
## Core Imports
14
15
```go
16
import tea "github.com/charmbracelet/bubbletea"
17
```
18
19
Alternative direct imports for specific functionality:
20
21
```go
22
import (
23
tea "github.com/charmbracelet/bubbletea"
24
"context"
25
"time"
26
)
27
```
28
29
## Basic Usage
30
31
```go
32
package main
33
34
import (
35
"fmt"
36
tea "github.com/charmbracelet/bubbletea"
37
)
38
39
// Define your model
40
type model struct {
41
choices []string
42
cursor int
43
selected map[int]struct{}
44
}
45
46
// Implement the Model interface
47
func (m model) Init() tea.Cmd {
48
// Return initial command (or nil for no initial command)
49
return nil
50
}
51
52
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
53
switch msg := msg.(type) {
54
case tea.KeyMsg:
55
switch msg.String() {
56
case "ctrl+c", "q":
57
return m, tea.Quit()
58
case "up", "k":
59
if m.cursor > 0 {
60
m.cursor--
61
}
62
case "down", "j":
63
if m.cursor < len(m.choices)-1 {
64
m.cursor++
65
}
66
}
67
}
68
return m, nil
69
}
70
71
func (m model) View() string {
72
s := "What should we buy at the grocery store?\n\n"
73
74
for i, choice := range m.choices {
75
cursor := " "
76
if m.cursor == i {
77
cursor = ">"
78
}
79
s += fmt.Sprintf("%s %s\n", cursor, choice)
80
}
81
82
s += "\nPress q to quit.\n"
83
return s
84
}
85
86
func main() {
87
m := model{
88
choices: []string{"Apples", "Oranges", "Bananas"},
89
selected: make(map[int]struct{}),
90
}
91
92
p := tea.NewProgram(m)
93
if _, err := p.Run(); err != nil {
94
fmt.Printf("Error: %v", err)
95
}
96
}
97
```
98
99
## Architecture
100
101
Bubble Tea is built around The Elm Architecture pattern with these key components:
102
103
- **Model Interface**: Represents application state and defines three core methods (Init, Update, View)
104
- **Message System**: All events flow through the Msg interface, enabling type-safe event handling
105
- **Command System**: Represents side effects and asynchronous operations that return messages
106
- **Program**: Manages the event loop, terminal state, and renders the UI
107
- **Renderer**: Handles ANSI escape codes, terminal control, and efficient screen updates
108
109
The architecture ensures predictable state management through immutable updates and clear separation of concerns between state (Model), logic (Update), and presentation (View).
110
111
## Capabilities
112
113
### Program Management
114
115
Core program lifecycle management including initialization, execution, and cleanup with full terminal state control.
116
117
```go { .api }
118
func NewProgram(model Model, opts ...ProgramOption) *Program
119
120
func (p *Program) Run() (Model, error)
121
func (p *Program) Send(msg Msg)
122
func (p *Program) Quit()
123
func (p *Program) Kill()
124
```
125
126
[Program Management](./program.md)
127
128
### Input Handling
129
130
Comprehensive keyboard and mouse input handling with support for all standard terminal input including function keys, mouse events, focus events, and bracketed paste.
131
132
```go { .api }
133
type KeyMsg Key
134
type MouseMsg MouseEvent
135
136
type Key struct {
137
Type KeyType
138
Runes []rune
139
Alt bool
140
Paste bool
141
}
142
143
type MouseEvent struct {
144
X int
145
Y int
146
Shift bool
147
Alt bool
148
Ctrl bool
149
Action MouseAction
150
Button MouseButton
151
}
152
```
153
154
[Input Handling](./input.md)
155
156
### Command System
157
158
Asynchronous operations and side effects through commands, including built-in commands for timers, batching, and external process execution.
159
160
```go { .api }
161
type Cmd func() Msg
162
163
func Batch(cmds ...Cmd) Cmd
164
func Sequence(cmds ...Cmd) Cmd
165
func Tick(d time.Duration, fn func(time.Time) Msg) Cmd
166
func Every(duration time.Duration, fn func(time.Time) Msg) Cmd
167
```
168
169
[Command System](./commands.md)
170
171
### Terminal Control
172
173
Complete terminal and screen control including alternate screen buffer, mouse modes, cursor control, focus reporting, and bracketed paste mode.
174
175
```go { .api }
176
func ClearScreen() Msg
177
func EnterAltScreen() Msg
178
func ExitAltScreen() Msg
179
func EnableMouseCellMotion() Msg
180
func EnableMouseAllMotion() Msg
181
func DisableMouse() Msg
182
```
183
184
[Terminal Control](./screen.md)
185
186
## Core Types
187
188
```go { .api }
189
// Core interfaces
190
type Model interface {
191
Init() Cmd
192
Update(Msg) (Model, Cmd)
193
View() string
194
}
195
196
type Msg interface{}
197
198
type Cmd func() Msg
199
200
// Program options
201
type ProgramOption func(*Program)
202
203
// Key and mouse types
204
type KeyType int
205
type MouseAction int
206
type MouseButton int
207
208
// Window size information
209
type WindowSizeMsg struct {
210
Width int
211
Height int
212
}
213
```
214
215
## Error Handling
216
217
```go { .api }
218
var (
219
ErrProgramPanic = errors.New("program experienced a panic")
220
ErrProgramKilled = errors.New("program was killed")
221
ErrInterrupted = errors.New("program was interrupted")
222
)
223
```
224
225
These errors are returned by `Program.Run()` under different termination conditions:
226
- `ErrProgramPanic`: Program recovered from a panic
227
- `ErrProgramKilled`: Program was forcibly terminated
228
- `ErrInterrupted`: Program received SIGINT or interrupt message