Bubble Tea v2: What’s New in v2 + How to Upgrade #1374
Replies: 7 comments 13 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/[email protected]Have 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.

Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Welcome to Bubble Tea v2
We're very excited to announce the forthcoming second major release of Bubble Tea! This document outlines the changes and improvements in Bubble Tea v2.0.0 and generally serves as a migration 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.
What’s new?
❤️ 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 this 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 call the shots, and in the context of this relationship, that lib is Bubble Tea.
But what about color downasampling? 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.
API Updates
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 the converted 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?
Changed: Key Messages
Key messages are now split into
tea.KeyPressMsgandtea.KeyReleaseMsg. Usetea.KeyMsgto match against both.We also no longer have
key.Typeandkey.Runesfields. These have been replaced withkey.Codeandkey.Textrespectively. A key code is just arunethat represents the key message. It can be a special key liketea.KeyEnter,tea.KeyTab,tea.KeyEscape, or a printable rune.The new
key.Textfield signifies a printable key event. If the key event has a non-emptyTextfield, it means the key event is a printable key event. In that case,key.Codeis always going to be the first rune ofkey.Text.Instead of matching against
msg.Type == tea.KeyCtrl...keys, key modifiers are now part of the key event itself askey.Mod. Shifted keys now have their own key code inkey.ShiftedCode. Typing shift+b will producekey.Code == 'b',key.ShiftedCode == 'B',key.Text == "B", andkey.Mod == tea.ModShift.The easiest way to match against key press/release events is to use
msg.String():Oh, and we finally changed space bar to return
"space"instead of" ". In this case,key.Code == ' 'andkey.Text == " ".Paste messages
Bubble Tea v1 supports bracketed-paste mode by default. It sends paste events as a
tea.KeyMsgwithmsg.Pasteflag set totrue, which to be honest, was pretty confusing.In Bubble Tea v2, paste events are sent as their own
tea.PasteMsgmessage. You can listen also listen to pastetea.PasteStartMsgandtea.PasteEndMsgevents to detect paste start and end events.Mouse messages
We've also improved the mouse API, which is a breaking change. Use
tea.MouseMsgto match against different types of mouse events. Mouse messages are split intotea.MouseClickMsg,tea.MouseReleaseMsg,tea.MouseWheelMsg, andtea.MouseMotionMsg.A Declarative View
In Bubble Tea v1, the
View()method always returned astring. This islimiting because it doesn't allow for additional metadata to be returned along
with the content to render. Additionally, it made it hard to extend the API in
the future.
In v2, we introduce a new
Viewtype that allows you to declare precisely howyour view should behave.
Now, if you want your program to run in alt-screen mode, you can simply set the
view.AltScreenfield totrue. No more fighting over options and commands!In Bubble Tea v2, the
Viewmethod returns atea.Viewstruct. This struct contains the content to render as well as additional metadata like cursor position, style, and visibility.An Actual Cursor
Another nice feature in Bubble Tea v2 is the ability to control the cursor. Now, the
tea.Modelinterface is split intotea.Modelandtea.ViewModel. Or if you're interested in controlling the cursor, you can use thetea.CursorModelinterface.The
tea.CursorModelinterface returns a*tea.Cursorstruct that contains the cursor's position, style, and visibility. Do you want it hidden? Sure, just returnniland everything will be taken care of.Progress Bar Support
Now you can ask Bubble Tea to render a native progress bar for your
application. Doing some async work and want to show progress? Just set the
view.ProgressBarfield and Bubble Tea will take care of the rest.Synchronized Updates (Mode 2026)
Now, 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.
Other new things
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. This is useful for creating advanced terminal applications.
To change the terminal's colors, set
view.ForegroundColor,view.BackgroundColor, andview.Cursor.Colorin yourView()function.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 XTVERSION control 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
What's that you say? You 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.
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 later 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 use 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.🌈 More on Bubble Tea v2
Just getting into Bubble Tea v2? Check out the full v2 release notes and upgrade guide.
Feedback
Have thoughts on Bubble Tea v2 Alpha? 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