Bubble Tea v2 - Full API Reference

Import: tea "charm.land/bubbletea/v2"

Key Constants

Special keys (use with Key.Code):

KeyUp, KeyDown, KeyLeft, KeyRight, KeyHome, KeyEnd, KeyPgUp, KeyPgDown
KeyInsert, KeyDelete, KeyFind, KeySelect, KeyBegin
KeyBackspace, KeyTab, KeyEnter, KeyReturn, KeyEscape, KeyEsc, KeySpace
KeyF1 through KeyF63
KeyCapsLock, KeyScrollLock, KeyNumLock, KeyPrintScreen, KeyPause, KeyMenu

Keypad keys: KeyKpEnter, KeyKp0-KeyKp9, KeyKpPlus, KeyKpMinus, KeyKpMultiply, KeyKpDivide, KeyKpDecimal, KeyKpEqual, KeyKpComma, KeyKpSep

Modifier keys: KeyLeftShift, KeyRightShift, KeyLeftAlt, KeyRightAlt, KeyLeftCtrl, KeyRightCtrl, KeyLeftSuper, KeyRightSuper, KeyLeftMeta, KeyRightMeta, KeyLeftHyper, KeyRightHyper

Modifier Constants

ModShift    // Shift key
ModAlt      // Alt/Option key
ModCtrl     // Control key
ModMeta     // Meta key
ModHyper    // Hyper key
ModSuper    // Super/Windows/Command key
ModCapsLock // Caps Lock state
ModNumLock  // Num Lock state

Key Struct

type Key struct {
    Text        string   // printable character(s) - empty for special keys
    Mod         KeyMod   // modifier keys bitmask
    Code        rune     // key code (e.g. KeyEnter, 'a')
    ShiftedCode rune     // shifted key (Kitty protocol only)
    BaseCode    rune     // base key per US layout (Kitty protocol only)
    IsRepeat    bool     // key repeat (Kitty protocol only)
}

Methods: String(), Keystroke()

String() returns the text if available, otherwise falls back to Keystroke(). Keystroke() returns modifier+key format: "ctrl+shift+alt+a" (modifiers always in this order: ctrl, alt, shift, meta, hyper, super).

Mouse Constants

MouseNone, MouseLeft, MouseMiddle, MouseRight
MouseWheelUp, MouseWheelDown, MouseWheelLeft, MouseWheelRight
MouseBackward, MouseForward, MouseButton10, MouseButton11

Mouse Struct

type Mouse struct {
    X, Y   int          // zero-based position, (0,0) = top-left
    Button MouseButton
    Mod    KeyMod
}

Mouse Messages

• MouseClickMsg - button pressed
• MouseReleaseMsg - button released
• MouseWheelMsg - scroll wheel
• MouseMotionMsg - mouse moved

All satisfy MouseMsg interface with .Mouse() Mouse and .String() string.

Mouse Modes

MouseModeNone        // disabled (default)
MouseModeCellMotion  // click, release, wheel, drag
MouseModeAllMotion   // all above + movement without buttons

View Struct

type View struct {
    Content                   string
    OnMouse                   func(MouseMsg) Cmd
    Cursor                    *Cursor
    BackgroundColor           color.Color
    ForegroundColor           color.Color
    WindowTitle               string
    ProgressBar               *ProgressBar
    AltScreen                 bool
    ReportFocus               bool
    DisableBracketedPasteMode bool
    MouseMode                 MouseMode
    KeyboardEnhancements      KeyboardEnhancements
}

NewView(s string) View - create View from string. SetContent(s string) - set view content.

Cursor

type Cursor struct {
    Position             // X, Y int
    Color    color.Color
    Shape    CursorShape // CursorBlock, CursorUnderline, CursorBar
    Blink    bool
}

NewCursor(x, y int) *Cursor - create cursor at position.

Program Methods

NewProgram(model Model, opts ...ProgramOption) *Program
(p *Program) Run() (Model, error)
(p *Program) Send(msg Msg)
(p *Program) Quit()
(p *Program) Kill()
(p *Program) Wait()

Error Variables

ErrProgramPanic  // recovered from panic
ErrProgramKilled // Kill() was called
ErrInterrupted   // SIGINT or InterruptMsg

Clipboard

SetClipboard(s string) Cmd         // set system clipboard
ReadClipboard() Msg                 // request clipboard content
SetPrimaryClipboard(s string) Cmd   // X11/Wayland primary
ReadPrimaryClipboard() Msg          // X11/Wayland primary

ClipboardMsg - received clipboard content. Fields: Content string, Selection byte.

Color Queries

RequestBackgroundColor() Msg    // returns BackgroundColorMsg
RequestForegroundColor() Msg    // returns ForegroundColorMsg
RequestCursorColor() Msg        // returns CursorColorMsg

Each response has IsDark() bool and String() string.

Progress Bar

type ProgressBar struct {
    State ProgressBarState  // ProgressBarNone/Default/Error/Indeterminate/Warning
    Value int               // 0-100
}

NewProgressBar(state ProgressBarState, value int) *ProgressBar

Logging

LogToFile(path, prefix string) (*os.File, error)
LogToFileWith(path, prefix string, log LogOptionsSetter) (*os.File, error)

Exec

Exec(cmd ExecCommand, fn ExecCallback) Cmd
ExecProcess(cmd *exec.Cmd, fn ExecCallback) Cmd

type ExecCallback func(error) Msg

Pauses the TUI, runs external process (e.g. vim), resumes on completion.