Three methods define the application loop
A Bubble Tea program has a model and 3 core methods. Init can start an initial command, Update receives messages and returns the next model, and View describes what the terminal should show. Key presses, timer ticks, window changes, and server responses all arrive as messages. The framework owns the event loop and rendering, while application state stays in ordinary Go values.
This shape is easy to reason about when a terminal app has more than a prompt and one response. State changes pass through Update, and commands return messages instead of mutating the screen directly. The trade is ceremony: even a shopping-list tutorial defines a model, message switch, view builder, and quit behavior. Developers who prefer a ready-made form or table object may find a widget-led library quicker.
Common controls live in Bubbles, outside the core module
Bubble Tea handles the program loop and terminal interface. Text inputs, viewports, spinners, and other reusable controls come from Charm's separate Bubbles project. Lip Gloss supplies styling and layout, while other linked libraries cover animation, mouse zones, and charts. That split keeps the framework focused, but a real application usually depends on more than the one module shown in the basic tutorial.
The core still covers substantial terminal mechanics. The README names a cell-based renderer, color downsampling, keyboard and mouse handling, native clipboard support, and inline or full-window output. Version 2 moves terminal preferences into the returned tea.View: alternate screen, mouse mode, focus reports, window title, cursor, colors, and keyboard features can follow model state rather than imperative commands scattered through the program.
What happened when we ran it
Our sandbox installed 21 Go packages in 28 seconds at commit 73b6d91. The build completed successfully in 20 seconds. Tests finished successfully in 10 seconds, with 2 passed and 0 failed of 2. Nothing in the supplied lab result showed a dependency, compiler, or test error.
The checkout was compact: 228 files, about 14,375 lines of source, and 3 MB. Our scan found 7 CI workflow files, no Dockerfile, and no separate tests directory. A Dockerfile is not expected for an embeddable Go framework, and Go test files normally sit beside package code, so the directory signal should not be read as an absence of testing. The measured result is simply that the 2 tests our harness counted passed.
The sandbox did not judge visual output, key decoding, paste behavior, Unicode width, or cleanup across real terminal emulators. Those are central to this library and need pseudo-terminal tests plus manual checks. The successful 58 seconds of install, build, and tests is a good source baseline, not a cross-platform UI certification.
Version 2 is declarative, but the migration touches many APIs
The v2 upgrade guide changes the import from GitHub to charm.land/bubbletea/v2 and changes View() from a string return to tea.View. Key presses use tea.KeyPressMsg; paste events have their own message types; mouse messages became interfaces with separate click, release, wheel, and motion types. Space now becomes space when converted to a string.
Program options and commands for alternate-screen mode, mouse tracking, focus reporting, cursor visibility, and window title were removed in favor of fields on the view. Several methods and names changed too. The guide provides a checklist and side-by-side examples, which lowers migration risk. It does not make the upgrade automatic. A mature v1 program with custom input handling should inventory every old option, command, and message assertion before switching.
Terminal edge cases deserve product-level tests
Open issue 1712 reports garbled clipboard paste on Windows with characters that could not be removed from an input. Issue 1777 says v2.0.9 still mishandles Traditional Chinese and Hindi graphemes in the reporter's example, while v1 rendered them correctly. These reports concern specific setups, but both affect basic text entry and display, so applications serving multilingual users should include their own corpus.
Renderer timing also has current reports. Issue 1590 shows escape characters printed when a program quits after a 10 ms timer before a full frame appears. Issue 1778 provides a reproduction in which output can freeze after tea.Exec returns quickly, naming both v1.3.10 and v2.0.9. Issue 1780 describes a stale frame during resize around the renderer's 60 Hz flush. Our 2-test lab run did not reproduce or refute them.
Test on the actual Windows, macOS, and Linux terminals you claim to support. Cover bracketed paste, wide and combining characters, resize bursts, early quit, suspend and resume, and commands that temporarily take over the terminal. File logging is the practical default because writing debug text to standard output corrupts the UI. The README also explains using a headless Go debugger on port 43000.
August 2026 maintenance is active around v2.0.9
GitHub recorded 44,696 stars, 206 combined open issues and pull requests, and a last push on August 19, 2026. Release v2.0.9 arrived the same day with fixes for key mapping, a progress-bar panic, terminal artifacts, and keyboard-stack restoration. Several issues were then updated through August 28, so code and issue activity both look current.
Bubble Tea is a strong default for Go developers who like reducers and explicit state. The measured setup is small and clean, the tutorial teaches the whole loop, and the v2 guide is candid about breaking changes. The remaining decision rests on interface style and terminal coverage: choose it for the architecture, then earn confidence by testing the terminals, scripts, and control transfers your users will encounter.