v2.0.0-rc.2

Smooth Operator (Mode 2026)

This release introduces synchronized output updates, which is enabled by default. This mode enhances how supported terminals render program updates by triggering the updates atomically.

We've also fixed a bunch of renderer bugs and edge cases 🙂

Changelog

New!

• 94247ed: feat: add SupportsKeyDisambiguation to KeyboardEnhancementsMsg (@aymanbagabas)
• f1799cd: feat: add synchronized updates option to renderer interface (@aymanbagabas)
• 7120058: feat: introduce ModeReportMsg for terminal mode reports (@aymanbagabas)
• 349783e: feat: query terminal for synchronized output support (mode 2026) (@aymanbagabas)
• d88ab58: feat: renderer: use uv altscreen helpers (@aymanbagabas)

Fixed

• 101fd11: Revert "fix: renderer: sync buffer resize with frame rate" (@aymanbagabas)
• 8f17c35: fix(examples): revert textarea pointers to values (@aymanbagabas)
• 78766cd: fix(examples): use updated progress bar blend api (@aymanbagabas)
• d9f7210: fix(renderer): avoid unnecessary resize on alt screen buffer (@aymanbagabas)
• 03b6524: fix: edge case where cursor visibility is the only change (@aymanbagabas)
• 1ef7dd4: fix: ensure TERM_PROGRAM is set (@aymanbagabas)
• 5133131: fix: renderer: always erase to end of line when prepending lines (@aymanbagabas)
• f206009: fix: renderer: always redraw on resize (@aymanbagabas)
• 2c7af7f: fix: renderer: avoid redundant cursor toggles (@aymanbagabas)
• 4687350: fix: renderer: check for cellbuf size change before skipping flush (@aymanbagabas)
• f19cb68: fix: renderer: defer resize and draw until flush (@aymanbagabas)
• 3a71934: fix: renderer: ensure prepended lines queued before render (@aymanbagabas)
• 83e606b: fix: renderer: handle cursor visibility and syncd output efficiently (@aymanbagabas)
• f01fc81: fix: renderer: reset cursor position in inline mode to avoid line wraps (@aymanbagabas)
• f952eb9: fix: renderer: use an interface for inline height calculation (@aymanbagabas)
• 1dcdea9: fix: renderer: use the correct size when resizing the screen (@aymanbagabas)
• aa0071e: fix: renderer: we want to always use the frame area for drawing (@aymanbagabas)

Docs

• 9878b7a: docs: update NewView and SetContent to add examples and notes (@aymanbagabas)
• cfe6724: docs: update code example formatting in screen.go (@aymanbagabas)
• 3780c0e: docs: update keyboard enhancement flags comment (@aymanbagabas)

Other stuff

• 514da28: perf: renderer: skip flush if no changes (@aymanbagabas)
• ed050cd: refactor: extract terminal capability detection into helper function (#1543) (@Copilot)
• f03c467: refactor: keyboard enhancements api improvements (#1534) (@aymanbagabas)
• a1ecb94: refactor: rename View.Layer to View.Content for clarity (#1536) (@aymanbagabas)
• c3c752d: refactor: renderer: support mode 2026, manage cursor visibility and altscreen (@aymanbagabas)

---

Thoughts? Questions? We love hearing from you. Feel free to reach out on X, Discord, Slack, The Fediverse, Bluesky.

v2.0.0-rc.1

This release includes a big change in the module name, and several message type changes. These types changed from type aliases to structs to improve extensibility and allow for future enhancements without breaking changes:

• github.com/charmbracelet/bubbletea/v2 - now moved to charm.land/bubbletea/v2
• CursorPositionMsg - now a struct type
• KeyboardEnhancementsMsg - now a struct type
• PasteMsg - now a struct type
• CapabilityMsg - now a struct type
• TerminalVersionMsg - now struct types

Migration Guide

Charm Land!

// Before
import tea "github.com/charmbracelet/bubbletea/v2"

// After
import tea "charm.land/bubbletea/v2"

Or you can use this GNU sed oneliner in your project root 😉

find . -name \*.go | xargs -I{} sed -i 's/"github.com\/charmbracelet\/bubbletea\/v2"/"charm.land\/bubbletea\/v2"/' {}

CursorPositionMsg

// Before
case CursorPositionMsg:
    x, y := msg.X, msg.Y

// After (no change needed - fields remain the same)
case CursorPositionMsg:
    x, y := msg.X, msg.Y

KeyboardEnhancementsMsg

// Before
case KeyboardEnhancementsMsg:
    if msg&ansi.KittyDisambiguateEscapeCodes != 0 {
        // ...
    }

// After
case KeyboardEnhancementsMsg:
    if msg.Flags&ansi.KittyDisambiguateEscapeCodes != 0 {
        // ...
    }
    // Or use the helper methods:
    if msg.SupportsKeyDisambiguation() {
        // ...
    }

PasteMsg

// Before
case PasteMsg:
    content := string(msg)

// After
case PasteMsg:
    content := msg.Content
    // Or use the String() method:
    content := msg.String()

CapabilityMsg

// Before
case CapabilityMsg:
    switch msg {
    case "RGB", "Tc":
        // ...
    }

// After
case CapabilityMsg:
    switch msg.Content {
    case "RGB", "Tc":
        // ...
    }
    // Or use the String() method:
    switch msg.String() {
    case "RGB", "Tc":
        // ...
    }

TerminalVersionMsg

// Before
case TerminalVersionMsg:
    version := string(msg)

// After
case TerminalVersionMsg:
    version := msg.Name
    // Or use the String() method:
    version := msg.String()

Changelog

Docs

• ff8c824: docs(examples): migrate imports to charm.land (@aymanbagabas)

Other stuff

• b947ade: refactor: change several message types to structs for extensibility (@aymanbagabas)
• cc0168c: refactor: migrate imports to charm.land domain (@aymanbagabas)
• b864579: refactor: update module path to charm.land/bubbletea/v2 (@aymanbagabas)

---

Thoughts? Questions? We love hearing from you. Feel free to reach out on X, Discord, Slack, The Fediverse, Bluesky.

v2.0.0-beta.6

Renderer Fixes

This new beta release includes a number of fixes related to the renderer.

Changelog

Fixed

• 4accb1c: fix: renderer: avoid requesting keyboard enhancements on close (@aymanbagabas)
• 6781fb5: fix: renderer: ensure we reset cursor style and color on close (@aymanbagabas)
• fa36fb1: fix: renderer: only move cursor to bottom when we're in the main screen (@aymanbagabas)
• d7c95b8: fix: renderer: sync buffer resize with frame rate (@aymanbagabas)

---

Thoughts? Questions? We love hearing from you. Feel free to reach out on X, Discord, Slack, The Fediverse, Bluesky.

v2.0.0-beta.5

Bubble Tea beta 5 is here!

We're excited to share the new Bubble Tea v2 beta 5 release with you! In this release, we focused on refining the View API, making it more declarative with a single source of truth for view-related properties.

Summary

All the changes since Beta 4 are to supporting a more declarative View type. This might sound like a lot but it's fairly simple in practice. This is what it looks like now:

func (m model) View() tea.View {
    v := tea.NewView("Hi, mom!")
    v.AltScreen = true
    v.WindowTitle = "It’s all about Mom today"
}

Why the change?

The general impetus for doing this is to eliminate the possibility of race conditions and greatly improve view performance. For example, the altscreen was previously triggered via a Cmd, which would not necessarily hit at the same moment the view was being rendered.

What else happened?

We've removed many view-based startup options and commands in favor of a more declarative approach using the View type. For example, WithMouseCellMotion() is now a property on View, i.e. view.MouseMode = tea.MouseModeCellMotion.

Now, the View() method returns a View struct that encapsulates all view-related properties. This change simplifies the API and makes it more intuitive to use with a single point of configuration for views.

The View API

Previously, Bubble Tea used functional options and commands to configure various view-related properties. This approach was flexible but led to a fragmented API surface. Should I use WithAltScreen() or EnterAltScreen? Is there a difference between them? Why can't I enable focus reporting with WithReportFocus() but not via a command?

These questions and inconsistencies led us to rethink how we handle view configuration. The new View struct consolidates all view-related properties, making it easier to understand and use with a single source of truth. I.e., this is how your view looks like, and these are its properties.

type View struct {
    Layer                     Layer        // Layer represents the content of the view
    Cursor                    *Cursor      // Position, style, color (nil = hidden)
    BackgroundColor           color.Color  // Terminal default background color
    ForegroundColor           color.Color  // Terminal default foreground color
    WindowTitle               string       // Window title
    ProgressBar               *ProgressBar // Progress bar (nil = no progressbar)
    AltScreen                 bool         // Alternate screen buffer (fullscreen mode)
    MouseMode                 MouseMode    // Mouse event mode
    ReportFocus               bool         // Focus/blur events
    DisableBracketedPasteMode bool         // Bracketed paste
    DisableKeyEnhancements    bool         // Keyboard enhancements
    KeyReleases               bool         // Key release events
    UniformKeyLayout          bool         // Uniform key layout
}

Options and Commands

We've removed many of the view-related options and commands that were previously set using functional options or commands. Instead, these properties are now part of the View struct returned by the View() method.

Removed options include:

• WithAltScreen() → View.AltScreen = true
• WithMouseCellMotion() → View.MouseMode = tea.MouseModeCellMotion
• WithMouseAllMotion() → View.MouseMode = tea.MouseModeAllMotion
• WithReportFocus() → View.ReportFocus = true
• WithKeyReleases() → View.KeyReleases = true
• WithUniformKeyLayout() → View.UniformKeyLayout = true
• WithoutBracketedPaste() → View.DisableBracketedPasteMode = true
• WithInputTTY() → use OpenTTY() and set input/output manually

Removed commands include:

• EnterAltScreen/ExitAltScreen → View.AltScreen
• SetBackgroundColor() → View.BackgroundColor
• SetForegroundColor() → View.ForegroundColor
• SetCursorColor() → View.Cursor.Color
• SetWindowTitle() → View.WindowTitle
• EnableMouseCellMotion/EnableMouseAllMotion/DisableMouse → View.MouseMode

Model Interface

The Model interface has been updated to make View() return a View struct instead of a string. We know that a string is often more convenient and easier to work with, however, due to the number of view-related options we wanted to support, we felt it was best to encapsulate them in a dedicated struct.

You can still use strings for your views of course! You just need to wrap them in a NewView() call, or use view.SetContent(yourString).

// Before
type Model interface {
    Init() Cmd
    Update(Msg) (Model, Cmd)
    View() string
    // Or...
    View() (string, *Cursor)
}

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

Example?

Let's get to the fun part! Here's a simple example that displays a text in the center of the screen using the alt-screen buffer.

package main

import (
	"fmt"
	"os"

	tea "github.com/charmbracelet/bubbletea/v2"
	"github.com/charmbracelet/lipgloss/v2"
)

type model struct {
	width, height int
}

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

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

func (m model) View() tea.View {
	var v tea.View
	content := lipgloss.NewStyle().
		Width(m.width).
		Height(m.height).
		AlignHorizontal(lipgloss.Center).
		AlignVertical(lipgloss.Center).
		Foreground(lipgloss.Cyan).
		Render(" Bubble Tea Beta 5! ")

	v.AltScreen = true
	v.SetContent(content)

	return v
}

func main() {
	p := tea.NewProgram(model{})
	if _, err := p.Run(); err != nil {
		fmt.Fprintf(os.Stderr, "Alas, there's been an error: %v", err)
	}
}

Like details?

Here’s the full changelog since v2.0.0-beta.4

Changelog

New!

• 7f2ee3d: feat(examples): add a canvas example (@aymanbagabas)
• 9ea9a8c: feat(examples): add clickable example (@aymanbagabas)
• e67ab35: feat(examples): add layer hit message to canvas example (@aymanbagabas)
• 19dc7c2: feat: add NewView helper function (@aymanbagabas)
• 94c70a4: feat: add OpenTTY to open the terminal's TTY (@aymanbagabas)
• f51fc36: feat: add helper method SetContent to View (@aymanbagabas)
• 9b921df: feat: add option to disable key enhancements (@aymanbagabas)
• 69b915a: feat: add support for setting terminal window title using the View API (@aymanbagabas)
• 4cafc09: feat: add support for terminal progress bars (#1499) (@aymanbagabas)
• f1eadf4: feat: embed mouse events in hit messages (@aymanbagabas)
• 1e6aaa5: feat: implement hit detection for layers in cursed renderer (@aymanbagabas)
• 98f59a4: feat: implement viewable model and layers (@aymanbagabas)
• c3a99ef: feat: input: use new uv input reader api (@aymanbagabas)
• 314b50c: feat: properly call nested sequenceMsg and batchMsg (@wolfmagnate)
• bd45f5b: feat: renderer: use the new promoted tv renderer (@aymanbagabas)
• 718c8e7: feat: restore WithoutRenderer option (@aymanbagabas)
• a73e084: feat: support setting terminal fg/bg using the View API (@aymanbagabas)
• 31fb503: feat: update to use uv package (@aymanbagabas)

Fixed

• 256e348: fix(examples): add newline to keyboard-enhancements example output (@aymanbagabas)
• 51804bc: fix(examples): ensure we have a newline at the end of the simple example (@aymanbagabas)
• 70e94a2: fix(keyboard): use kitty keyboard state command (@aymanbagabas)
• 3b687ff: fix(progress): reset on shutdown (#1511) (@caarlos0)
• f9df81b: fix(renderer): clear screen on exit when not using alt screen (@aymanbagabas)
• d4d69f6: fix(renderer): drop lines from top of buffer when frame height exceeds screen height (@aymanbagabas)
• 73b42b8: fix(renderer): only send non-empty layer hit messages (@aymanbagabas)
• 28ab4f4: fix(renderer): properly reset cursor position to start of line (#1472) (@aymanbagabas)
• 56ff714: fix(renderer): reset cursor style on close (@aymanbagabas)
• cf6866f: fix: add View to Model interface and introduce DisableRenderer field (@aymanbagabas)
• c76509a: fix: compact sequences like batches (#958) (@jdhenke)
• ab0bc8e: fix: correct event type name (@aymanbagabas)
• d2ecd81: fix: cursed_renderer: use Erase instead of Clear (@aymanbagabas)
• 875f553: fix: disable modifyOtherKeys for tmux (@aymanbagabas)
• c4303e1: fix: dry passed width and height to newCursedRenderer and send resize (@aymanbagabas)
• 30a273a...

v1.3.10

Changelog

Bug fixes

• 9edf69c: fix: handle setWindowTitleMsg and windowSizeMsg in eventLoop (@aymanbagabas)

---

Thoughts? Questions? We love hearing from you. Feel free to reach out on X, Discord, Slack, The Fediverse, Bluesky.

v1.3.9

Changelog

New Features

• 314b50c: feat: properly call nested sequenceMsg and batchMsg (@wolfmagnate)

Bug fixes

• 9e0e8f0: fix: recover from nested panics in Sequence and Batch commands (@aymanbagabas)

Other work

• 6e1282a: add example for the nested Sequence and Batch (@wolfmagnate)
• 0290af4: simplify case for BatchMsg (@wolfmagnate)

---

Thoughts? Questions? We love hearing from you. Feel free to reach out on Twitter, Discord, Slack, The Fediverse.

v1.3.8

Changelog

Bug fixes

• 21eecd5: fix: send batch commands to cmds channel instead of executing them in event loop (#1473) (@aymanbagabas)

---

Thoughts? Questions? We love hearing from you. Feel free to reach out on Twitter, Discord, Slack, The Fediverse.

v1.3.7

Changelog

Bug fixes

• 28ab4f4: fix(renderer): properly reset cursor position to start of line (#1472) (@aymanbagabas)
• c76509a: fix: compact sequences like batches (#958) (@jdhenke)
• f5da8d0: fix: handle nested SequenceMsg in event loop and use sync.WaitGroup f… (#1463) (@aymanbagabas)
• 80ea844: fix: lint issues in key_windows.go and tty_windows.go (@aymanbagabas)

Documentation updates

• c3136ed: docs(license): update copyright date range (@meowgorithm)
• 919805f: docs(readme): update footer art (@meowgorithm)
• f01583b: docs: show the correct branch in the build badge (@aymanbagabas)

Other work

• a81d6f3: ci: sync dependabot config (#1480) (@charmcli)
• 53609c1: ci: sync golangci-lint config (#1466) (@github-actions[bot])

---

Thoughts? Questions? We love hearing from you. Feel free to reach out on Twitter, Discord, Slack, The Fediverse.

v2.0.0-beta.4

How’s it going?

This is a small beta release with a few changes and a bunch of bug fixes. Enjoy!

Keyboard

WithKeyboardEnhancements has been split into three separate functions for clarity:

• WithKeyReleases: Enables support for reporting key release events.
• WithUniformKeyLayout: Enables support for reporting key events in a uniform layout format.
• RequestKeyDisambiguation: Enables support for disambiguated key events.

Debugging Panics

You can now set TEA_DEBUG to true to dump panic logs to the current directory.

export TEA_DEBUG=1

Changelog

New Features

• 3ce0c24: feat: create a panic trace file (#1446) (@aymanbagabas)
• 99a80e6: feat: keyboard: split keyboard enhancements into separate functions (@aymanbagabas)

Bug fixes

• 576a623: fix(example): fix keyboard-enhancements example (@andreynering)
• b62fc32: fix(examples): tui-daemon-combo: modelView must also implement Init and Update (@aymanbagabas)
• f97ba58: fix(key): add Keystroke() method to KeyPressMsg and KeyReleaseMsg (@aymanbagabas)
• b152063: fix(tutorials): update basics tutorial per v2 tea.Model changes (@meowgorithm)
• 0a63003: fix: Windows: first character input lost on successive programs (#1368) (@joshallenit)
• 78ed49b: fix: maintain exec output (#1276) (@raphaelvigee)
• 536b713: fix: remove unused keyboardc channel (@aymanbagabas)
• 65af983: fix: renderer: reset cursor state on close (@aymanbagabas)
• 185e281: fix: renderer: use mapnl when terminal is not a tty (@aymanbagabas)

Documentation updates

• af1fcd3: docs(examples): update textinput and textarea examples per Bubbles v2 API changes (#1425) (@meowgorithm)
• 1b0f489: docs(readme): cleanup badges (@meowgorithm)
• f502dc5: docs: add isbn form validation example (#1401) (@DerMaddis)
• a806274: docs: tidy (@bashbunni)

Other work

• ca9473b: ci: sync golangci-lint config (#1431) (@github-actions[bot])
• 42c169a: docs(examples/textinput): support virtual cursor (@meowgorithm)

---

Thoughts? Questions? We love hearing from you. Feel free to reach out on Twitter, The Fediverse, or on Discord.

v1.3.6

This version fixes some important issues regarding tea.Exec output after resuming from the executed program, and Windows losing input character on successive program execution.

Big thanks to @raphaelvigee and @joshallenit for working on these issues, you're the best!

Changelog

Bug fixes

• 0a63003: fix: Windows: first character input lost on successive programs (#1368) (@joshallenit)
• 78ed49b: fix: maintain exec output (#1276) (@raphaelvigee)

Documentation updates

• 1b0f489: docs(readme): cleanup badges (@meowgorithm)

Other work

• ca9473b: ci: sync golangci-lint config (#1431) (@github-actions[bot])

---

Thoughts? Questions? We love hearing from you. Feel free to reach out on Twitter, The Fediverse, or on Discord.