Bubble Tea v2: What’s New in v2 #1374
Replies: 9 comments 17 replies
-
|
Congratulations on the release, just a quick question - are bugfixes for main branch (V1) code still actively wanted or should pull requests be tailored directly to v2-exp branch (V2) code? Just asking for problems that may exist both in V1 and V2 code - would you like respective pull requests for both branches or just V2? Is V1 now EOL or are there still going to be (bugfix) releases? 😉 |
Beta Was this translation helpful? Give feedback.
-
|
Looking forward to upgrade! But, the link full v2 release notes and upgrade guide. is pointing to example.com |
Beta Was this translation helpful? Give feedback.
-
|
FYI I tried From The following works without any issues: by commit: by branch: |
Beta Was this translation helpful? Give feedback.
-
|
I'm kinda sad that the other bubbles/related libraries don't have v2 stuff yet 😦 I wanna use both! Guess I'll have to either make PRs or switch to just the central charm libraries. (Yes I'm using beta libraries right now, and yes patience is a virtue lol) |
Beta Was this translation helpful? Give feedback.
-
|
We just announced Bubble Tea beta 5! Get it while it's hot! go get github.com/charmbracelet/bubbletea/v2@v2.0.0-beta.5Have thoughts on Bubble Tea v2 beta 5? We’d love to hear about it. |
Beta Was this translation helpful? Give feedback.
-
|
Now v6 of the beta is out is out! |
Beta Was this translation helpful? Give feedback.
-
|
Hey everyone, we just released the second RC release! We're getting there, expect v2.0.0 very soon!! |
Beta Was this translation helpful? Give feedback.
-
|
View struct includes so many fields that will most likely be unused for so many programs. For example: how many do you have to toggle alt screen mode on call to View? Same goes for other fields too. |
Beta Was this translation helpful? Give feedback.
-
|
Does anyone have advice for upgrading the various Charm imports when go: charm.land/lipgloss/v2@upgrade (v2.0.0-beta.3) requires charm.land/lipgloss/v2@v2.0.0-beta.3: parsing go.mod:
module declares its path as: github.com/charmbracelet/lipgloss/v2
but was required as: charm.land/lipgloss/v2There is surprisingly little information on this condition online and nothing I found helped |
Beta Was this translation helpful? Give feedback.

Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
What's New in Bubble Tea v2
We're very excited to announce the second major release of Bubble Tea!
If you (or your LLM) are just looking for technical details on migrating from v1, please check out the Upgrade Guide.
Note
We don't take API changes lightly and strive to make the upgrade process as simple as possible. We believe the changes bring necessary improvements as well as pave the way for the future. If something feels way off, let us know.
❤️ Charm Land Import Path
We've updated our import paths to use vanity domains and use our domain to import Go packages.
Everything else stays the same 🙂
👾 The Cursed Renderer
Bubble Tea v2 ships with the all-new Cursed Renderer which was built from the ground up. It's based on the ncurses rendering algorithm and is highly optimized for speed, efficiency, and accuracy and is built on an enormous amount of research and development.
Optimized renders also means that Wish users get big performance benefits and lower bandwidth usage by orders of magnitude.
To take advantage of the new Cursed Renderer you don't need to do anything at all except keep on using the Bubble Tea you know and love.
✌️ Key handling is way better now
Newer terminals can now take advantage of all sorts keyboard input via progressive keyboard enhancements. You can now map all sorts of keys and modifiers like shift+enter and super+space. You can also detect key releases (we're looking at you, game developers).
It's easy to detect support for supporting terminals and add fallbacks for those that don't. For details, see keyboard enhancements below.
🥊 No more fighting
In the past, Bubble Tea and Lip Gloss would often fight over i/o. Bubble Tea wanted to read keyboard input and Lip Gloss wanted to query for the background color. This means that things could get messy. Not anymore! In v2, Lip Gloss is now pure, which means, Bubble Tea manages i/o and gives orders to Lip Gloss. In short, we only need one lib to call the shots, and in the context of this relationship, that lib is Bubble Tea.
But what about color downsampling? That's a great question.
👨🏻🎨 Built-in Color Downsampling
We sneakily released a little library called colorprofile that will detect the terminal's color profile and auto-downsample any ANSI styling that flows through it to the best available color profile. This means that color will "just work" (and not misbehave) no matter where the ANSI styling comes from.
Downsampling is built-into Bubble Tea and is automatically enabled.
🧘 Declarative, Not Imperative
This is a big one. In v1, you'd toggle terminal features on and off with commands like
tea.EnterAltScreen,tea.EnableMouseCellMotion,tea.EnableReportFocus, and so on. In v2, all of that is gone and replaced by fields on theViewstruct. You just declare what you want your view to look like and Bubble Tea takes care of the rest.This means no more fighting over startup options and commands. Just set the fields and forget about it. For example, to enter full screen mode:
The same goes for mouse mode, bracketed paste, focus reporting, window title, keyboard enhancements, and more. See A Declarative View below for the full picture.
Keyboard Enhancements
Progressive keyboard enhancements allow you to receive key events not normally possible in traditional terminals. For example, you can now listen for the ctrl+m key, as well as previously unavailable key combinations like shift+enter.
Bubble Tea v2 will always try to enable basic keyboard enhancements that disambiguate keys. If your terminal supports it, your program will receive a
tea.KeyboardEnhancementsMsgmessage that indicates support for requested features.Historically, certain key combinations in terminals map to control codes. For example, ctrl+h outputs a backspace by default, which means you can't normally bind a key event to ctrl+h. With key disambiguation, you can now actually bind events to those key combinations.
You can detect if a terminal supports keyboard enhancements by listening for
tea.KeyboardEnhancementsMsg.Which terminals support progressive enhancement?
Key Messages
Key messages are now split into
tea.KeyPressMsgandtea.KeyReleaseMsg. Usetea.KeyMsgto match against both. We've also replacedkey.Typeandkey.Runeswithkey.Codeandkey.Text. Modifiers live inkey.Modnow instead of being separate booleans. Oh, and space bar returns"space"instead of" ".The easiest way to match against key press events is to use
msg.String():The
Keystruct also has some nice new fields:key.BaseCode— the key according to a standard US PC-101 layout. Handy for international keyboards where the physical key might differ.key.IsRepeat— tells you if the key is being held down and auto-repeating. Only available with the Kitty Keyboard Protocol or Windows Console API.key.Keystroke()— a new method that returns the keystroke representation (e.g.,"ctrl+shift+alt+a"). UnlikeString(), it always includes modifier info.For the full list of changes and before/after code samples, see the Upgrade Guide.
Paste Messages
Paste events used to arrive as
tea.KeyMsgwith a confusingmsg.Pasteflag. Now they're their own thing:Mouse Messages
We've improved the mouse API. Mouse messages are now split into
tea.MouseClickMsg,tea.MouseReleaseMsg,tea.MouseWheelMsg, andtea.MouseMotionMsg. And mouse mode is set declaratively in yourView():A Declarative View
In v1,
View()returned astring. In v2, it returns atea.Viewstruct that lets you declare everything about your view — content, cursor, alt screen, mouse mode, colors, window title, progress bar, and more:No more fighting over options and commands! Just set the fields:
An Actual Cursor
You can now control the cursor position, color, and shape right from your view function. Want it hidden? Just set
view.Cursor = nil.You can also use
tea.NewCursor(x, y)for a quick block cursor with default settings.Progress Bar Support
Now you can ask Bubble Tea to render a native progress bar for your application. Just set the
view.ProgressBarfield and Bubble Tea will take care of the rest.Synchronized Updates (Mode 2026)
Bubble Tea will try and use mode 2026 to push updates to the terminal. This mode helps reduce tearing and cursor flickering by atomically updating the terminal window once all the update sequences are pushed out and read by the terminal. This is enabled by default and there's nothing you need to do.
Better Terminal Unicode Support (mode 2027)
Now Bubble Tea will automatically enable mode 2027
on terminals that support it. This mode allows the terminal to properly handle wide Unicode
characters and emojis without breaking the layout of your app. Again, this is
enabled by default and there's nothing you need to do.
Native Clipboard Support
Bubble Tea now supports native clipboard operations, also known as OSC52. This means you can even copy and paste over SSH!
X11 and Wayland users can also use
tea.SetPrimaryClipboardto set the primary clipboard. Note that this is a very niche sort of thing and may or may not work on macOS, Windows, and other platforms without the notion of more than one clipboard.Terminal Colors
You can now read and set the terminal's foreground, background, and cursor colors. To change them, set
view.ForegroundColor,view.BackgroundColor, andview.Cursor.Colorin yourView()function.🌍 Environment Variables
Bubble Tea now sends you a
tea.EnvMsgat startup with the environment variables. This is especially handy for SSH apps whereos.Getenvwould give you the server's environment, not the client's.🔮 Raw Escape Sequences
For the power users out there, you can now send raw escape sequences directly to the terminal with
tea.Raw. This is great for querying terminal capabilities or doing things Bubble Tea doesn't have a built-in for (yet).Responses from the terminal will come back as messages in
Update. Just be sure you know what you're doing — with great power comes great terminal weirdness.📍 Cursor Position Queries
Need to know where the cursor is? Now you can ask.
📊 Terminal Mode Reports
You can query whether the terminal supports specific modes (like focus events or synchronized output) using DECRPM mode reports. Send a raw DECRQM request and listen for
tea.ModeReportMsg.Terminal Version and Name
Don't know what terminal you're running in?
$TERMis too vague? Bubble Tea now has atea.RequestTerminalVersioncommand that queries the terminal for its name and version using the XTVERSION escape sequence.Note
This feature is not supported by all terminals.
Terminfo and Termcap Capabilities
Sometimes you need to know what capabilities the terminal has. Bubble Tea now has a
tea.RequestCapabilitycommand that queries the terminal for a specific terminfo/termcap capability.Note
This feature is not supported by all terminals.
Detecting the Color Profile
Need to use the detected color profile in your app? Listen to
tea.ColorProfileMsginUpdate:Manually Applying a Color Profile
Want to manually set a color profile for testing? Now you can, on the program level.
Want to hard detect the color profile in Wish? We bet you do.
🪟 Window Size for Testing
When running tests or in non-interactive environments, you can now set the initial terminal size:
No more mocking terminals just to run your tests. Nice!
Use the Terminal's TTY
Sometimes your program will write to stdout while it's being piped or
redirected. In these cases, you might want to write directly to the terminal's
TTY instead of stdout because stdout might not be a terminal. Or your program
expects to read from stdin but stdin is being piped from another program.
In Bubble Tea v1, there wasn't a good way to do this. In the latter case, you
could use the
WithInputTTY()option to read from the terminal's TTY insteadof stdin. However, there was no easy way to write to the terminal's TTY instead
of stdout without fiddling with file descriptors.
In Bubble Tea v2, you can now simply use the global
OpenTTY()to open theterminal's TTY for reading and writing. You can then pass the TTY file handles
to the
WithInput()andWithOutput()options.Note that Bubble Tea v2 will always use the TTY for input when input is not specified
via
WithInput(...).🌈 More on Bubble Tea v2
Ready to migrate? Head over to the Upgrade Guide for the full migration checklist.
Feedback
Have thoughts on Bubble Tea v2? We'd love to hear about it. Let us know on…
Part of Charm.
Charm热爱开源 • Charm loves open source • نحنُ نحب المصادر المفتوحة
Beta Was this translation helpful? Give feedback.
All reactions