Add bloom to an existing program
Move a working Bubble Tea v2 program onto bloom one step at a time, keeping its model and components, and replacing size math and Join calls with a layout.
You don't have to rewrite a Bubble Tea program to use bloom. Your model, your Update, and your components stay as
they are. What changes is the root View: it returns a tree of nodes instead of one string, and bloom does the
sizing, placing, and mouse routing you used to do by hand.
This page moves a program over in small steps, each of which builds and runs. It assumes the program is already on Bubble Tea v2 and Lip Gloss v2; see Installation. If it uses bubblezone for the mouse, also read Migrating from bubblezone.
Where you start
A typical program keeps the window's size, splits it between panes with arithmetic, and joins the rendered panes into one string:
type model struct {
width, height int
list list.Model
reader viewport.Model
}
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
case tea.WindowSizeMsg:
m.width, m.height = msg.Width, msg.Height
m.list.SetSize(24, m.height-1)
m.reader.SetWidth(m.width - 24 - 2)
m.reader.SetHeight(m.height - 1 - 2)
// ...
}
// ...
}
func (m model) View() tea.View {
sidebar := m.list.View()
reader := panel.Width(m.width - 24).Height(m.height - 1).Render(m.reader.View())
status := statusStyle.Width(m.width).Render(m.status())
v := tea.NewView(lipgloss.JoinVertical(lipgloss.Left,
lipgloss.JoinHorizontal(lipgloss.Top, sidebar, reader),
status,
))
v.AltScreen = true
return v
}Every number in there depends on every other: change the sidebar's width, or the panel's border, and the reader's size is wrong.
Add a root
A bloom.Root renders the layout and keeps what it can between frames.
Keep one in the model, return its Init from yours, and pass it every message:
type model struct {
ui *bloom.Root
width, height int
list list.Model
reader viewport.Model
}
func (m *model) Init() tea.Cmd { return m.ui.Init() }
func (m *model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
var cmds []tea.Cmd
// ... your existing cases, appending to cmds ...
cmds = append(cmds, m.ui.Update(msg))
return m, tea.Batch(cmds...)
}m := &model{ui: bloom.New() /* ... */}Options such as bloom.WithFocus go to bloom.New, and you
can add them later.
Switch the model's methods to pointer receivers while you're here. The mouse handlers you'll add later are closures
made in View, and with a value receiver they'd change a copy of the model. See
Change state, or send a message.
Return the root's view
Wrap the string you already build in a bloom.Text and hand it to m.ui.View. bloom now draws
the frame, and it should look the same as before, unless the view holds escape sequences other than styles and
hyperlinks (see Things to watch for):
func (m *model) View() tea.View {
v := m.ui.View(m.width, m.height, bloom.Text(m.oldView()))
v.AltScreen = true
return v
}m.ui.View returns a tea.View, so the fields you set on it before, such as AltScreen, are set the same way. It
sets MouseMode for you, to the least the frame's handlers need. This frame has none yet, so if Update still
handles the mouse itself, keep setting yours after the call until you
move that handling onto nodes.
Replace Join calls with rows and columns
Each lipgloss.JoinHorizontal becomes a bloom.Row and each JoinVertical a bloom.Column. A component goes in
as it is: anything with a View() string method is a node. Wrap each child in a slot that says
how it shares the space, and a box for anything that had a border:
func (m *model) layout() bloom.Child {
return bloom.Column(
bloom.Fill(bloom.Row(
bloom.Fixed(24, m.list),
bloom.Fill(bloom.Box(panel, m.reader)),
)),
bloom.Fixed(1, bloom.Text(m.status()).Style(statusStyle)),
)
}
func (m *model) View() tea.View {
v := m.ui.View(m.width, m.height, m.layout())
v.AltScreen = true
return v
}The widths and heights you passed to Lip Gloss styles are gone. bloom gives each child its space, and a Box draws
the border around what's left inside, so a thicker border or more padding no longer breaks the math.
You can do this a piece at a time. A pane you haven't converted yet can stay a bloom.Text of its old string inside
the new row.
Give components their sizes
bloom places a component's view, but it can't call SetWidth on it for you. Components that size themselves, such
as Bubbles' viewport and list, still need to be told their size in Update. Rather than working it out with
arithmetic, give the slot an ID and ask bloom where it went:
type pane int
const paneReader pane = iota
// in layout
bloom.Fill(bloom.Box(panel, m.reader)).ID(paneReader)case tea.WindowSizeMsg:
m.width, m.height = msg.Width, msg.Height
if r, ok := bloom.Solve(m.width, m.height, m.layout()).Rect(paneReader); ok {
m.reader.SetWidth(r.Dx() - panel.GetHorizontalFrameSize())
m.reader.SetHeight(r.Dy() - panel.GetVerticalFrameSize())
}The slot's rectangle includes the box's border, so subtract the style's frame size to get the space inside.
Using Bubbles components covers each common component,
and Sizes and positions in Update explains when to use Solve and when to read the
last frame.
Move mouse handling onto the nodes
If Update checks mouse coordinates against where you think things were drawn, put a handler on the node instead.
The handler runs only for events on that node:
for i, name := range m.names {
rows[i] = bloom.Text(name).On(on.Click(func() tea.Cmd {
m.selected = i
return nil
}))
}The tea.MouseClickMsg and other mouse messages still reach Update, so remove the old handling as you go, or an
event is acted on twice. Once it's all gone, stop setting MouseMode and let bloom choose it. See
Mouse events.
From here, the rest of bloom is there when you want it: dialogs and toasts drawn over the screen, keyboard focus, panes that collapse on small terminals, and animation.
Use a layout inside a string view
If you'd rather not change the root View yet, bloom.Render lays
out and draws a tree as a string, which you can join with the rest of your view as before:
help := bloom.Render(m.width, 0, bloom.Row(
bloom.Fill(bloom.Text("↑/↓ move")),
bloom.Fill(bloom.Text("enter open")),
bloom.Fill(bloom.Text("q quit")),
))A height of zero draws the layout at its natural height. Render keeps nothing between calls, so a layout drawn
this way has no mouse handlers, focus, hover styles, or layout animation. Use it as a stepping stone, or for parts
of a view that only need placing.
Things to watch for
- Value receivers. Handlers made in a
Viewwith a value receiver change a copy, in the root model or in a child component. See Change state, or send a message. - Pre-rendered sizes. A string you render at a fixed width with
style.Width(n).Render(...)keeps that width. Pass the style toBoxorText(...).Style(...)instead, so it's drawn at the size it's given. - Escape sequences.
Textdrops escape sequences other than styles and hyperlinks, such as inline images. A component's view is drawn as it is. See Text from outside your program.
Related
bloom.Rootandbloom.RenderAPI reference- Build your first layout, the same pieces from an empty screen
- How a bloom program runs, for what the root does with each message and frame
- Using Bubbles components
- Writing components, for components that lay themselves out
- Migrating from bubblezone
Last updated on
Add a dialog and a toast
A tutorial that adds a confirmation dialog with a dimmed backdrop, keyboard focus, and an auto-hiding toast notification to the notes app.
How layout works
The model behind bloom's layout - constraints go down, sizes come up, parents place - and why the tree is rebuilt every frame.