tea

func Batch ¶

func Batch(cmds ...Cmd) Cmd

Batch performs a bunch of commands concurrently with no ordering guarantees about the results. Use a Batch to return several commands.

Example:

    func (m model) Init() (Model, Cmd) {
	       return m, tea.Batch(someCommand, someOtherCommand)
    }

func Every ¶

func Every(duration time.Duration, fn func(time.Time) Msg) Cmd

Every is a command that ticks in sync with the system clock. So, if you wanted to tick with the system clock every second, minute or hour you could use this. It's also handy for having different things tick in sync.

Because we're ticking with the system clock the tick will likely not run for the entire specified duration. For example, if we're ticking for one minute and the clock is at 12:34:20 then the next tick will happen at 12:35:00, 40 seconds later.

To produce the command, pass a duration and a function which returns a message containing the time at which the tick occurred.

type TickMsg time.Time

cmd := Every(time.Second, func(t time.Time) Msg {
   return TickMsg(t)
})

Beginners' note: Every sends a single message and won't automatically dispatch messages at an interval. To do that, you'll want to return another Every command after receiving your tick message. For example:

type TickMsg time.Time

// Send a message every second.
func tickEvery() Cmd {
    return Every(time.Second, func(t time.Time) Msg {
        return TickMsg(t)
    })
}

func (m model) Init() (Model, Cmd) {
    // Start ticking.
    return m, tickEvery()
}

func (m model) Update(msg Msg) (Model, Cmd) {
    switch msg.(type) {
    case TickMsg:
        // Return your Every command again to loop.
        return m, tickEvery()
    }
    return m, nil
}

Every is analogous to Tick in the Elm Architecture.

func Exec ¶

func Exec(c ExecCommand, fn ExecCallback) Cmd

Exec is used to perform arbitrary I/O in a blocking fashion, effectively pausing the Program while execution is running and resuming it when execution has completed.

Most of the time you'll want to use ExecProcess, which runs an exec.Cmd.

For non-interactive i/o you should use a Cmd (that is, a tea.Cmd).

func ExecProcess ¶

func ExecProcess(c *exec.Cmd, fn ExecCallback) Cmd

ExecProcess runs the given *exec.Cmd in a blocking fashion, effectively pausing the Program while the command is running. After the *exec.Cmd exists the Program resumes. It's useful for spawning other interactive applications such as editors and shells from within a Program.

To produce the command, pass an *exec.Cmd and a function which returns a message containing the error which may have occurred when running the ExecCommand.

type VimFinishedMsg struct { err error }

c := exec.Command("vim", "file.txt")

cmd := ExecProcess(c, func(err error) Msg {
    return VimFinishedMsg{err: err}
})

Or, if you don't care about errors, you could simply:

cmd := ExecProcess(exec.Command("vim", "file.txt"), nil)

For non-interactive i/o you should use a Cmd (that is, a tea.Cmd).

func Printf ¶

func Printf(template string, args ...interface{}) Cmd

Printf prints above the Program. It takes a format template followed by values similar to fmt.Printf. This output is unmanaged by the program and will persist across renders by the Program.

Unlike fmt.Printf (but similar to log.Printf) the message will be print on its own line.

If the altscreen is active no output will be printed.

func Println ¶

func Println(args ...interface{}) Cmd

Println prints above the Program. This output is unmanaged by the program and will persist across renders by the Program.

Unlike fmt.Println (but similar to log.Println) the message will be print on its own line.

If the altscreen is active no output will be printed.

func Raw ¶

func Raw(r any) Cmd

Raw is a command that prints the given string to the terminal without any formatting.

This is intended for advanced use cases where you need to query the terminal or send escape sequences directly. Don't use this unless you know what you're doing :)

Example:

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
  switch msg := msg.(type) {
  case input.PrimaryDeviceAttributesEvent:
    for _, attr := range msg {
      if attr == 4 {
        // We have Sixel graphics support!
        break
      }
    }
  }

  // Request the terminal primary device attributes to detect Sixel graphics
  // support.
  return m, tea.Raw(ansi.RequestPrimaryDeviceAttributes)
}

func RequestCapability ¶

func RequestCapability(s string) Cmd

RequestCapability is a command that requests the terminal to send its Termcap/Terminfo response for the given capability.

Bubble Tea recognizes the following capabilities and will use them to upgrade the program's color profile:

• "RGB" Xterm direct color
• "Tc" True color support

Note: that some terminal's like Apple's Terminal.app do not support this and will send the wrong response to the terminal breaking the program's output.

When the Bubble Tea advertises a non-TrueColor profile, you can use this command to query the terminal for its color capabilities. Example:

switch msg := msg.(type) {
case tea.ColorProfileMsg:
  if msg.Profile != colorprofile.TrueColor {
    return m, tea.Batch(
      tea.RequestCapability("RGB"),
      tea.RequestCapability("Tc"),
    )
  }
}

func RequestKeyboardEnhancements ¶

func RequestKeyboardEnhancements(enhancements ...KeyboardEnhancementOption) Cmd

RequestKeyboardEnhancements is a command that enables keyboard enhancements in the terminal.

This command can be used to request specific keyboard enhancements. Use this command to request enabling support for key disambiguation. You can also request other enhancements by passing additional options. For example:

• WithKeyReleases enables support for reporting release key events.
• WithUniformKeyLayout enables support for reporting key events as though they were on a PC-101 layout.

If the terminal supports the requested enhancements, it will send a KeyboardEnhancementsMsg message with the supported enhancements.

Note that not all terminals support all enhancements.

func Sequence ¶

func Sequence(cmds ...Cmd) Cmd

Sequence runs the given commands one at a time, in order. Contrast this with Batch, which runs commands concurrently.

func SetBackgroundColor ¶

func SetBackgroundColor(c color.Color) Cmd

SetBackgroundColor is a command that sets the terminal background color.

func SetClipboard ¶

func SetClipboard(s string) Cmd

SetClipboard produces a command that sets the system clipboard using OSC52. Note that OSC52 is not supported in all terminals.

func SetCursorColor ¶

func SetCursorColor(c color.Color) Cmd

SetCursorColor is a command that sets the terminal cursor color.

func SetForegroundColor ¶

func SetForegroundColor(c color.Color) Cmd

SetForegroundColor is a command that sets the terminal foreground color.

func SetPrimaryClipboard ¶

func SetPrimaryClipboard(s string) Cmd

SetPrimaryClipboard produces a command that sets the primary clipboard using OSC52. Primary clipboard selection is a feature present in X11 and Wayland only. Note that OSC52 is not supported in all terminals.

func SetWindowTitle ¶

func SetWindowTitle(title string) Cmd

SetWindowTitle produces a command that sets the terminal title.

For example:

func (m model) Init() (Model, Cmd) {
    // Set title.
    return m, tea.SetWindowTitle("My App")
}

func Tick ¶

func Tick(d time.Duration, fn func(time.Time) Msg) Cmd

Tick produces a command at an interval independent of the system clock at the given duration. That is, the timer begins precisely when invoked, and runs for its entire duration.

To produce the command, pass a duration and a function which returns a message containing the time at which the tick occurred.

type TickMsg time.Time

cmd := Tick(time.Second, func(t time.Time) Msg {
   return TickMsg(t)
})

Beginners' note: Tick sends a single message and won't automatically dispatch messages at an interval. To do that, you'll want to return another Tick command after receiving your tick message. For example:

type TickMsg time.Time

func doTick() Cmd {
    return Tick(time.Second, func(t time.Time) Msg {
        return TickMsg(t)
    })
}

func (m model) Init() (Model, Cmd) {
    // Start ticking.
    return m, doTick()
}

func (m model) Update(msg Msg) (Model, Cmd) {
    switch msg.(type) {
    case TickMsg:
        // Return your Tick command again to loop.
        return m, doTick()
    }
    return m, nil
}

func NewCursor ¶

func NewCursor(x, y int) *Cursor

NewCursor returns a new cursor with the default settings and the given position.

func ClearScreen ¶

func ClearScreen() Msg

ClearScreen is a special command that tells the program to clear the screen before the next update. This can be used to move the cursor to the top left of the screen and clear visual clutter when the alt screen is not in use.

Note that it should never be necessary to call ClearScreen() for regular redraws.

func DisableBracketedPaste ¶

func DisableBracketedPaste() Msg

DisableBracketedPaste is a special command that tells the Bubble Tea program to accept bracketed paste input.

Note that bracketed paste will be automatically disabled when the program quits.

func DisableGraphemeClustering ¶

func DisableGraphemeClustering() Msg

DisableGraphemeClustering is a special command that tells the Bubble Tea program to disable grapheme clustering. This mode will be disabled automatically when the program quits.

func DisableKeyboardEnhancements ¶

func DisableKeyboardEnhancements() Msg

DisableKeyboardEnhancements is a command that disables keyboard enhancements in the terminal.

func DisableMouse ¶

func DisableMouse() Msg

DisableMouse is a special command that stops listening for mouse events.

func DisableReportFocus ¶

func DisableReportFocus() Msg

DisableReportFocus is a special command that tells the Bubble Tea program to disable focus reporting.

func EnableBracketedPaste ¶

func EnableBracketedPaste() Msg

EnableBracketedPaste is a special command that tells the Bubble Tea program to accept bracketed paste input.

Note that bracketed paste will be automatically disabled when the program quits.

func EnableGraphemeClustering ¶

func EnableGraphemeClustering() Msg

EnableGraphemeClustering is a special command that tells the Bubble Tea program to enable grapheme clustering. This is enabled by default.

func EnableMouseAllMotion ¶

func EnableMouseAllMotion() Msg

EnableMouseAllMotion is a special command that enables mouse click, release, wheel, and motion events, which are delivered regardless of whether a mouse button is pressed, effectively enabling support for hover interactions.

Many modern terminals support this, but not all. If in doubt, use EnableMouseCellMotion instead.

Because commands run asynchronously, this command should not be used in your model's Init function. Use the WithMouseAllMotion ProgramOption instead.

func EnableMouseCellMotion ¶

func EnableMouseCellMotion() Msg

EnableMouseCellMotion is a special command that enables mouse click, release, and wheel events. Mouse movement events are also captured if a mouse button is pressed (i.e., drag events).

Because commands run asynchronously, this command should not be used in your model's Init function. Use the WithMouseCellMotion ProgramOption instead.

func EnableReportFocus ¶

func EnableReportFocus() Msg

EnableReportFocus is a special command that tells the Bubble Tea program to enable focus reporting.

func EnterAltScreen ¶

func EnterAltScreen() Msg

EnterAltScreen is a special command that tells the Bubble Tea program to enter the alternate screen buffer.

Because commands run asynchronously, this command should not be used in your model's Init function. To initialize your program with the altscreen enabled use the WithAltScreen ProgramOption instead.

func ExitAltScreen ¶

func ExitAltScreen() Msg

ExitAltScreen is a special command that tells the Bubble Tea program to exit the alternate screen buffer. This command should be used to exit the alternate screen buffer while the program is running.

Note that the alternate screen buffer will be automatically exited when the program quits.

func HideCursor ¶

func HideCursor() Msg

HideCursor is a special command for manually instructing Bubble Tea to hide the cursor. In some rare cases, certain operations will cause the terminal to show the cursor, which is normally hidden for the duration of a Bubble Tea program's lifetime. You will most likely not need to use this command.

func Interrupt ¶

func Interrupt() Msg

Interrupt is a special command that tells the Bubble Tea program to interrupt.

func Quit ¶

func Quit() Msg

Quit is a special command that tells the Bubble Tea program to exit.

func ReadClipboard ¶

func ReadClipboard() Msg

ReadClipboard produces a command that reads the system clipboard using OSC52. Note that OSC52 is not supported in all terminals.

func ReadPrimaryClipboard ¶

func ReadPrimaryClipboard() Msg

ReadPrimaryClipboard produces a command that reads the primary clipboard using OSC52. Primary clipboard selection is a feature present in X11 and Wayland only. Note that OSC52 is not supported in all terminals.

func RequestBackgroundColor ¶

func RequestBackgroundColor() Msg

RequestBackgroundColor is a command that requests the terminal background color.

func RequestCursorColor ¶

func RequestCursorColor() Msg

RequestCursorColor is a command that requests the terminal cursor color.

func RequestCursorPosition ¶

func RequestCursorPosition() Msg

RequestCursorPosition is a command that requests the cursor position. The cursor position will be sent as a CursorPositionMsg message.

func RequestForegroundColor ¶

func RequestForegroundColor() Msg

RequestForegroundColor is a command that requests the terminal foreground color.

func RequestWindowSize ¶

func RequestWindowSize() Msg

RequestWindowSize is a command that queries the terminal for its current size. It delivers the results to Update via a WindowSizeMsg. Keep in mind that WindowSizeMsgs will automatically be delivered to Update when the Program starts and when the window dimensions change so in many cases you will not need to explicitly invoke this command.

func ShowCursor ¶

func ShowCursor() Msg

ShowCursor is a special command for manually instructing Bubble Tea to show the cursor.

func Suspend ¶

func Suspend() Msg

Suspend is a special command that tells the Bubble Tea program to suspend.

func TerminalVersion ¶

func TerminalVersion() Msg

TerminalVersion is a command that queries the terminal for its version using XTVERSION. Note that some terminals may not support this command.

func NewProgram ¶

func NewProgram(model Model, opts ...ProgramOption) *Program

NewProgram creates a new Program.

func WithAltScreen ¶

func WithAltScreen() ProgramOption

WithAltScreen starts the program with the alternate screen buffer enabled (i.e. the program starts in full window mode). Note that the altscreen will be automatically exited when the program quits.

Example:

p := tea.NewProgram(Model{}, tea.WithAltScreen())
if _, err := p.Run(); err != nil {
    fmt.Println("Error running program:", err)
    os.Exit(1)
}

To enter the altscreen once the program has already started running use the EnterAltScreen command.

func WithColorProfile ¶

func WithColorProfile(profile colorprofile.Profile) ProgramOption

WithColorProfile sets the color profile that the program will use. This is useful when you want to force a specific color profile. By default, Bubble Tea will try to detect the terminal's color profile from environment variables and terminfo capabilities. Use tea.WithEnvironment to set custom environment variables.

func WithContext ¶

func WithContext(ctx context.Context) ProgramOption

WithContext lets you specify a context in which to run the Program. This is useful if you want to cancel the execution from outside. When a Program gets cancelled it will exit with an error ErrProgramKilled.

func WithEnvironment ¶

func WithEnvironment(env []string) ProgramOption

WithEnvironment sets the environment variables that the program will use. This useful when the program is running in a remote session (e.g. SSH) and you want to pass the environment variables from the remote session to the program.

Example:

var sess ssh.Session // ssh.Session is a type from the github.com/charmbracelet/ssh package
pty, _, _ := sess.Pty()
environ := append(sess.Environ(), "TERM="+pty.Term)
p := tea.NewProgram(model, tea.WithEnvironment(environ)

func WithFPS ¶

func WithFPS(fps int) ProgramOption

WithFPS sets a custom maximum FPS at which the renderer should run. If less than 1, the default value of 60 will be used. If over 120, the FPS will be capped at 120.

func WithFilter ¶

func WithFilter(filter func(Model, Msg) Msg) ProgramOption

WithFilter supplies an event filter that will be invoked before Bubble Tea processes a tea.Msg. The event filter can return any tea.Msg which will then get handled by Bubble Tea instead of the original event. If the event filter returns nil, the event will be ignored and Bubble Tea will not process it.

As an example, this could be used to prevent a program from shutting down if there are unsaved changes.

Example:

func filter(m tea.Model, msg tea.Msg) tea.Msg {
	if _, ok := msg.(tea.QuitMsg); !ok {
		return msg
	}

	model := m.(myModel)
	if model.hasChanges {
		return nil
	}

	return msg
}

p := tea.NewProgram(Model{}, tea.WithFilter(filter));

if _,err := p.Run(); err != nil {
	fmt.Println("Error running program:", err)
	os.Exit(1)
}

func WithGraphemeClustering ¶

func WithGraphemeClustering() ProgramOption

WithGraphemeClustering disables grapheme clustering. This is useful if you want to disable grapheme clustering for your program.

Grapheme clustering is a character width calculation method that accurately calculates the width of wide characters in a terminal. This is useful for properly rendering double width characters such as emojis and CJK characters.

See https://mitchellh.com/writing/grapheme-clusters-in-terminals

func WithInput ¶

func WithInput(input io.Reader) ProgramOption

WithInput sets the input which, by default, is stdin. In most cases you won't need to use this. To disable input entirely pass nil.

p := NewProgram(model, WithInput(nil))

func WithInputTTY ¶

func WithInputTTY() ProgramOption

WithInputTTY opens a new TTY for input (or console input device on Windows).

func WithKeyboardEnhancements ¶

func WithKeyboardEnhancements(enhancements ...KeyboardEnhancementOption) ProgramOption

WithKeyboardEnhancements enables support for enhanced keyboard features. You can enable different keyboard features by passing one or more KeyboardEnhancement functions.

This is not supported on all terminals. On Windows, these features are enabled by default.

func WithMouseAllMotion ¶

func WithMouseAllMotion() ProgramOption

WithMouseAllMotion starts the program with the mouse enabled in "all motion" mode.

EnableMouseAllMotion is a special command that enables mouse click, release, wheel, and motion events, which are delivered regardless of whether a mouse button is pressed, effectively enabling support for hover interactions.

This will try to enable the mouse in extended mode (SGR), if that is not supported by the terminal it will fall back to normal mode (X10).

Many modern terminals support this, but not all. If in doubt, use EnableMouseCellMotion instead.

To enable the mouse once the program has already started running use the EnableMouseAllMotion command. To disable the mouse when the program is running use the DisableMouse command.

The mouse will be automatically disabled when the program exits.

func WithMouseCellMotion ¶

func WithMouseCellMotion() ProgramOption

WithMouseCellMotion starts the program with the mouse enabled in "cell motion" mode.

Cell motion mode enables mouse click, release, and wheel events. Mouse movement events are also captured if a mouse button is pressed (i.e., drag events). Cell motion mode is better supported than all motion mode.

This will try to enable the mouse in extended mode (SGR), if that is not supported by the terminal it will fall back to normal mode (X10).

To enable mouse cell motion once the program has already started running use the EnableMouseCellMotion command. To disable the mouse when the program is running use the DisableMouse command.

The mouse will be automatically disabled when the program exits.

func WithOutput ¶

func WithOutput(output io.Writer) ProgramOption

WithOutput sets the output which, by default, is stdout. In most cases you won't need to use this.

func WithReportFocus ¶

func WithReportFocus() ProgramOption

WithReportFocus enables reporting when the terminal gains and loses focus. When this is enabled FocusMsg and BlurMsg messages will be sent to your Update method.

Note that while most terminals and multiplexers support focus reporting, some do not. Also note that tmux needs to be configured to report focus events.

func WithWindowSize ¶

func WithWindowSize(width, height int) ProgramOption

WithWindowSize sets the initial size of the terminal window. This is useful when you need to set the initial size of the terminal window, for example during testing or when you want to run your program in a non-interactive environment.

func WithoutBracketedPaste ¶

func WithoutBracketedPaste() ProgramOption

WithoutBracketedPaste starts the program with bracketed paste disabled.

func WithoutCatchPanics ¶

func WithoutCatchPanics() ProgramOption

WithoutCatchPanics disables the panic catching that Bubble Tea does by default. If panic catching is disabled the terminal will be in a fairly unusable state after a panic because Bubble Tea will not perform its usual cleanup on exit.

func WithoutSignalHandler ¶

func WithoutSignalHandler() ProgramOption

WithoutSignalHandler disables the signal handler that Bubble Tea sets up for Programs. This is useful if you want to handle signals yourself.

func WithoutSignals ¶

func WithoutSignals() ProgramOption

WithoutSignals will ignore OS signals. This is mainly useful for testing.