Writing components
Build reusable components that lay themselves out for their space, report their size, handle their own mouse events, keep their IDs apart from other instances, and take keys from their parent.
Any type with a View() string method can go in a bloom layout, so a component you already have needs nothing
bloom-specific. This page is about components that go further: ones that change shape with their size, handle their
own clicks, and can appear more than once on a screen.
It builds a row of tabs as the example. The complete component is at the end.
Lay out for the space you're given
A component that implements bloom.Layouter returns a bloom
layout instead of a string. bloom calls its Layout method with a
bloom.Context, whose Width and Height are the space it has:
type Tabs struct {
Labels []string
Active int
}
func (t *Tabs) Layout(ctx bloom.Context) bloom.Child {
// Not room for every label in full. A width of zero is its natural size, such as from View.
short := ctx.Width > 0 && ctx.Width < t.width()
tabs := make([]bloom.Child, len(t.Labels))
for i, label := range t.Labels {
if short {
label = ansi.Truncate(label, 1, "")
}
style := tabStyle
if i == t.Active {
style = activeStyle
}
tabs[i] = bloom.Text(label).Style(style)
}
return bloom.Row(tabs...)
} inbox sent drafts wide enough
i s d narrowLayout may be called more than once a frame, while bloom measures as well as for the final layout, so it must not
change the component. Treat it like View: read state, return nodes. Responsive layouts has
more on changing shape with size.
A Layouter still needs a View method, for when it's used outside a bloom layout, such as by a program that
doesn't use bloom. bloom.Render with a size of zero draws the
layout at its natural size:
func (t *Tabs) View() string {
return bloom.Render(0, 0, t.Layout(bloom.Context{}))
}Report a natural size
A component that isn't a Layouter is measured by rendering its view. When it knows its size without that, it can
say so by implementing bloom.Measurer. A status bar is one row
tall at any width:
type statusbar struct{ text string }
func (s statusbar) View() string { return " " + s.text }
func (s statusbar) Measure(bloom.Size) bloom.Size {
return bloom.Size{W: lipgloss.Width(s.View()), H: 1}
}Return the size the component needs, not the space it's offered: when a layout is drawn at its natural size, the space offered is unbounded. The result is clamped to the space there is.
Handle the mouse inside the component
A component can put mouse handlers on the nodes it returns, so the parent doesn't need to know where its parts are. A handler can change the component, as long as it reaches the real one rather than a copy: give the component pointer receivers, and put a pointer to it in the tree.
tabs[i] = bloom.Text(label).Style(style).
On(on.Click(func() tea.Cmd { return t.pick(i) }))func (t *Tabs) pick(i int) tea.Cmd {
t.Active = i
id := t.ID
return func() tea.Msg { return TabMsg{ID: id, Active: i} }
}The handler changes the tabs, then returns a command that tells the parent, which handles TabMsg in its Update
like any other message. The parent keeps the tabs by value and places a pointer to them:
type model struct {
ui *bloom.Root
main Tabs
// ...
}
// in View
bloom.Column(bloom.Auto(&m.main), bloom.Fill(body))With value receivers, or m.main in place of &m.main, the click changes a copy and does nothing. If a component
must be kept by value, such as one written for Bubble Tea's usual m.c, cmd = m.c.Update(msg) pattern, have its
handlers send a message with on.Msg and change state in its own Update instead. See
Change state, or send a message.
Read the frame from a handler
A component has no root to ask where things went, so its handlers read the frame from the Context that Layout
was given. ctx.Frame() returns the frame on screen when it's called, which in a handler is the frame the event
landed in. Called from Layout itself, it's the frame before, and outside a root, such as with Render, it's nil.
A list in a component uses it to scroll from where the list actually was.
Know which side a layer opened on
A component drawn in a layer anchored to a node can ask ctx.Side() which side of the node the
layer was placed against, which flips when it doesn't fit. A dropdown uses it to draw its open edge facing its
field.
Give each instance its own IDs
IDs must be unique in a frame, and two instances of Tabs on one screen would
otherwise give their nodes the same ones. Have the parent give each instance an ID, and build the IDs of its parts
from it:
type Tabs struct {
ID any // set by the parent, unique to this instance
Labels []string
Active int
}
// tabID is the ID of one tab of a Tabs.
type tabID struct {
tabs any
i int
}
// in Layout
tabs[i] = bloom.Text(label).Style(style).ID(tabID{t.ID, i})
// ...
return bloom.Row(tabs...).ID(t.ID).Focusable()Taking the ID as any lets the parent use its own ID type, so the component's root node joins the parent's
focus order. A Focus moves between nodes whose IDs have its type, whatever the field's type:
type control int
const (
tabsMain control = iota
tabsSide
)
m.main = Tabs{ID: tabsMain, Labels: []string{"inbox", "sent", "drafts"}}
m.side = Tabs{ID: tabsSide, Labels: []string{"people", "labels"}}The ID must be comparable, like any ID. The unexported tabID type keeps the parts' IDs apart from everything
else's, and the parent can still find one, such as with m.ui.Frame().Rect(...), if the component exports a way
to make it.
Place components you're given
A container, such as a stack of panels, places children it didn't build. It can still make some of them focusable,
and keep that apart from the code that decides how each is placed: wrap a child that should take focus in an
Auto slot with its ID before placing it. Here the children say
whether they take focus by implementing an interface of the container's:
// Focuser is a child of a Stack that takes focus, by the ID it returns.
type Focuser interface {
bloom.Child
FocusID() any
}
// focusable makes c a stop in the tab order if it's a Focuser.
func focusable(c bloom.Child) bloom.Child {
if f, ok := c.(Focuser); ok {
return bloom.Auto(c).ID(f.FocusID()).Focusable()
}
return c
}Outside a row, column, or grid, a slot's sizing does nothing: it takes the space its parent gives it and passes it
on, so the wrapped child is laid out as it would be without the slot. In a row or column, the container places it in
a slot of its own, which decides the size. A grid sizes a slot in its cell as a row would, so in a grid, place it in
a Fill to fill the cell:
// in a column, the outer slot decides the size
bloom.Column(bloom.Fixed(3, focusable(s.header)), bloom.Fill(focusable(s.body)))
// in a list, each item is whatever item returns
bloom.List(len(s.items), func(i int) bloom.Child { return focusable(s.items[i]) })
// in a grid, a Fill fills the cell
bloom.Grid(2, bloom.Fill(focusable(s.left)), bloom.Fill(focusable(s.right)))Wrap the child, rather than adding the ID to the slot it's placed in. A list has no slot for each
item, and the code that picks Fixed or Fill stays the same whether or not a child takes focus. A child that marks
its own nodes focusable, as Tabs does, needs no wrapping.
Take keys from the parent
Keys aren't routed to nodes; they go to the parent's Update. Give the component an Update method of its own, and
have the parent call it while the component has focus. For a click on the tabs to focus them, give the root the
parent's focus with bloom.WithFocus(&m.focus):
// Update moves between tabs with the arrow keys.
func (t *Tabs) Update(msg tea.Msg) tea.Cmd {
if msg, ok := msg.(tea.KeyPressMsg); ok {
switch msg.String() {
case "left":
return t.pick(max(t.Active-1, 0))
case "right":
return t.pick(min(t.Active+1, len(t.Labels)-1))
}
}
return nil
} case tea.KeyPressMsg:
cmd, ok := m.focus.Update(msg, m.ui.Frame())
if !ok {
switch id, _ := m.focus.Current(); id {
case tabsMain:
cmd = m.main.Update(msg)
case tabsSide:
cmd = m.side.Update(msg)
}
}Pass on any other messages the component needs, such as its own TabMsg or animation frames, the same way. See
Route keys to the focused node.
The complete component
package main
import (
"bloomfx.dev/bloom"
"bloomfx.dev/bloom/on"
tea "charm.land/bubbletea/v2"
"charm.land/lipgloss/v2"
"github.com/charmbracelet/x/ansi"
)
var (
tabStyle = lipgloss.NewStyle().Padding(0, 1)
activeStyle = tabStyle.Reverse(true)
)
// Tabs is a row of tabs, one of which is active.
type Tabs struct {
ID any // set by the parent, unique to this instance
Labels []string
Active int
}
// TabMsg is sent when the user picks a tab.
type TabMsg struct {
ID any
Active int
}
// tabID is the ID of one tab of a Tabs.
type tabID struct {
tabs any
i int
}
// View draws the tabs on their own, outside a bloom layout.
func (t *Tabs) View() string {
return bloom.Render(0, 0, t.Layout(bloom.Context{}))
}
// Layout shows each label in full when there's room, and only its first
// letter when there isn't.
func (t *Tabs) Layout(ctx bloom.Context) bloom.Child {
short := ctx.Width > 0 && ctx.Width < t.width() // zero is its natural size
tabs := make([]bloom.Child, len(t.Labels))
for i, label := range t.Labels {
if short {
label = ansi.Truncate(label, 1, "")
}
style := tabStyle
if i == t.Active {
style = activeStyle
}
tabs[i] = bloom.Text(label).Style(style).ID(tabID{t.ID, i}).
On(on.Click(func() tea.Cmd { return t.pick(i) }))
}
return bloom.Row(tabs...).ID(t.ID).Focusable()
}
// Update moves between tabs with the arrow keys. The parent calls it while
// the tabs have focus.
func (t *Tabs) Update(msg tea.Msg) tea.Cmd {
if msg, ok := msg.(tea.KeyPressMsg); ok {
switch msg.String() {
case "left":
return t.pick(max(t.Active-1, 0))
case "right":
return t.pick(min(t.Active+1, len(t.Labels)-1))
}
}
return nil
}
func (t *Tabs) pick(i int) tea.Cmd {
t.Active = i
id := t.ID
return func() tea.Msg { return TabMsg{ID: id, Active: i} }
}
// width is how wide the tabs are with their full labels.
func (t *Tabs) width() int {
w := 0
for _, label := range t.Labels {
w += ansi.StringWidth(label) + tabStyle.GetHorizontalFrameSize()
}
return w
}A test can click a tab by its ID, with m.ui.Click:
m.View()
if _, ok := m.ui.Click(tabID{tabsMain, 1}); !ok || m.main.Active != 1 {
t.Fatal("the sent tab was not picked")
}Related
Layouter,Measurer, andContextAPI reference- How a bloom program runs, for what IDs are for
- Responsive layouts
- Keep the dropdown with its component
- Using Bubbles components
Last updated on
Sizes and positions in Update
Find where a node goes, and how big it is, from Update, with Solve for the state you have now or Frame for what's on screen, for paging, clamping, and components that need their size up front.
Testing
Test bloom layouts with Render, Solve, and Debug in plain unit tests, click nodes by ID, keep golden files, make animations deterministic, and test whole programs end to end with steep.