1# Bubble Tea v2 - Full API Reference
2
3Import: `tea "charm.land/bubbletea/v2"`
4
5## Key Constants
6
7Special keys (use with `Key.Code`):
8
9```
10KeyUp, KeyDown, KeyLeft, KeyRight, KeyHome, KeyEnd, KeyPgUp, KeyPgDown
11KeyInsert, KeyDelete, KeyFind, KeySelect, KeyBegin
12KeyBackspace, KeyTab, KeyEnter, KeyReturn, KeyEscape, KeyEsc, KeySpace
13KeyF1 through KeyF63
14KeyCapsLock, KeyScrollLock, KeyNumLock, KeyPrintScreen, KeyPause, KeyMenu
15```
16
17Keypad keys: `KeyKpEnter`, `KeyKp0`-`KeyKp9`, `KeyKpPlus`, `KeyKpMinus`, `KeyKpMultiply`, `KeyKpDivide`, `KeyKpDecimal`, `KeyKpEqual`, `KeyKpComma`, `KeyKpSep`
18
19Modifier keys: `KeyLeftShift`, `KeyRightShift`, `KeyLeftAlt`, `KeyRightAlt`, `KeyLeftCtrl`, `KeyRightCtrl`, `KeyLeftSuper`, `KeyRightSuper`, `KeyLeftMeta`, `KeyRightMeta`, `KeyLeftHyper`, `KeyRightHyper`
20
21## Modifier Constants
22
23```go
24ModShift // Shift key
25ModAlt // Alt/Option key
26ModCtrl // Control key
27ModMeta // Meta key
28ModHyper // Hyper key
29ModSuper // Super/Windows/Command key
30ModCapsLock // Caps Lock state
31ModNumLock // Num Lock state
32```
33
34## Key Struct
35
36```go
37type Key struct {
38 Text string // printable character(s) - empty for special keys
39 Mod KeyMod // modifier keys bitmask
40 Code rune // key code (e.g. KeyEnter, 'a')
41 ShiftedCode rune // shifted key (Kitty protocol only)
42 BaseCode rune // base key per US layout (Kitty protocol only)
43 IsRepeat bool // key repeat (Kitty protocol only)
44}
45```
46
47Methods: `String()`, `Keystroke()`
48
49String() returns the text if available, otherwise falls back to Keystroke().
50Keystroke() returns modifier+key format: `"ctrl+shift+alt+a"` (modifiers always in this order: ctrl, alt, shift, meta, hyper, super).
51
52## Mouse Constants
53
54```go
55MouseNone, MouseLeft, MouseMiddle, MouseRight
56MouseWheelUp, MouseWheelDown, MouseWheelLeft, MouseWheelRight
57MouseBackward, MouseForward, MouseButton10, MouseButton11
58```
59
60## Mouse Struct
61
62```go
63type Mouse struct {
64 X, Y int // zero-based position, (0,0) = top-left
65 Button MouseButton
66 Mod KeyMod
67}
68```
69
70## Mouse Messages
71
72- `MouseClickMsg` - button pressed
73- `MouseReleaseMsg` - button released
74- `MouseWheelMsg` - scroll wheel
75- `MouseMotionMsg` - mouse moved
76
77All satisfy `MouseMsg` interface with `.Mouse() Mouse` and `.String() string`.
78
79## Mouse Modes
80
81```go
82MouseModeNone // disabled (default)
83MouseModeCellMotion // click, release, wheel, drag
84MouseModeAllMotion // all above + movement without buttons
85```
86
87## View Struct
88
89```go
90type View struct {
91 Content string
92 OnMouse func(MouseMsg) Cmd
93 Cursor *Cursor
94 BackgroundColor color.Color
95 ForegroundColor color.Color
96 WindowTitle string
97 ProgressBar *ProgressBar
98 AltScreen bool
99 ReportFocus bool
100 DisableBracketedPasteMode bool
101 MouseMode MouseMode
102 KeyboardEnhancements KeyboardEnhancements
103}
104```
105
106`NewView(s string) View` - create View from string.
107`SetContent(s string)` - set view content.
108
109## Cursor
110
111```go
112type Cursor struct {
113 Position // X, Y int
114 Color color.Color
115 Shape CursorShape // CursorBlock, CursorUnderline, CursorBar
116 Blink bool
117}
118```
119
120`NewCursor(x, y int) *Cursor` - create cursor at position.
121
122## Program Methods
123
124```go
125NewProgram(model Model, opts ...ProgramOption) *Program
126(p *Program) Run() (Model, error)
127(p *Program) Send(msg Msg)
128(p *Program) Quit()
129(p *Program) Kill()
130(p *Program) Wait()
131```
132
133## Error Variables
134
135```go
136ErrProgramPanic // recovered from panic
137ErrProgramKilled // Kill() was called
138ErrInterrupted // SIGINT or InterruptMsg
139```
140
141## Clipboard
142
143```go
144SetClipboard(s string) Cmd // set system clipboard
145ReadClipboard() Msg // request clipboard content
146SetPrimaryClipboard(s string) Cmd // X11/Wayland primary
147ReadPrimaryClipboard() Msg // X11/Wayland primary
148```
149
150`ClipboardMsg` - received clipboard content. Fields: `Content string`, `Selection byte`.
151
152## Color Queries
153
154```go
155RequestBackgroundColor() Msg // returns BackgroundColorMsg
156RequestForegroundColor() Msg // returns ForegroundColorMsg
157RequestCursorColor() Msg // returns CursorColorMsg
158```
159
160Each response has `IsDark() bool` and `String() string`.
161
162## Progress Bar
163
164```go
165type ProgressBar struct {
166 State ProgressBarState // ProgressBarNone/Default/Error/Indeterminate/Warning
167 Value int // 0-100
168}
169
170NewProgressBar(state ProgressBarState, value int) *ProgressBar
171```
172
173## Logging
174
175```go
176LogToFile(path, prefix string) (*os.File, error)
177LogToFileWith(path, prefix string, log LogOptionsSetter) (*os.File, error)
178```
179
180## Exec
181
182```go
183Exec(cmd ExecCommand, fn ExecCallback) Cmd
184ExecProcess(cmd *exec.Cmd, fn ExecCallback) Cmd
185
186type ExecCallback func(error) Msg
187```
188
189Pauses the TUI, runs external process (e.g. vim), resumes on completion.