Skip to Content
bloom

Long lists

Show thousands of rows of components with List, building only those in view, keep a cursor in view, page by what fit, and scroll with the wheel and a scrollbar.

bloom.List(count, item) shows as many of count items as fit, top to bottom. It calls item(i) only for the items it may show, so a list of a million rows costs no more to draw than the rows on screen. Each item is as wide as the list and as tall as it wants, and the last one that doesn't fit is cut off:

bloom.List(len(m.logs), func(i int) bloom.Child {
	return bloom.Text(m.logs[i]).Style(line)
}).Offset(m.offset).ID(paneLogs)

Offset(i) is the first item shown. The list clamps it, so an offset past the end shows the last page, full, rather than space below it. Gap(n) puts n cells between items.

Use a list for rows of components, such as a file picker, a table, or a feed with items of different heights. For lines of text, a viewport does more, such as wrapping, search, and selecting text scrolled out of sight.

Don't put a list inside a Scroll: with no limit on its height, it lays out every item.

Keep the cursor in view

Keep(i) scrolls the list as little as it can from its offset so that item i is shown whole. Give it the item under a cursor, and moving the cursor is all the model does:

func (m *model) layout() bloom.Child {
	return bloom.List(len(m.items), m.row).Offset(m.offset).Keep(m.cursor).ID(paneItems)
}

Read where it ended up

Items can have different heights, so the list, not the model, knows where it ended up. Read it back with Frame().List(id), and keep First as the offset to scroll from next time. Visible is how many items were shown whole, which is how far to page:

case tea.KeyPressMsg:
	v, _ := m.ui.Frame().List(paneItems)
	m.offset = v.First
	switch msg.String() {
	case "down":
		m.cursor++
	case "pgdown":
		m.cursor += max(v.Visible-1, 1)
	}
	m.cursor = min(max(m.cursor, 0), len(m.items)-1)

Read the frame each time a key arrives, rather than keeping what it said last time: a resize, or Keep, moves the list without a key.

Scroll with the wheel

While Keep is given, the list can't scroll away from that item, so to scroll with the wheel, move the cursor along with the offset:

bloom.List(len(m.items), m.row).Offset(m.offset).Keep(m.cursor).ID(paneItems).
	On(on.Scroll(func(_, dy int) tea.Cmd {
		v, _ := m.ui.Frame().List(paneItems)
		m.offset = max(v.First+dy*3, 0)
		m.cursor = min(max(m.cursor, m.offset), m.offset+v.Visible-1, len(m.items)-1)
		return nil
	}))

Or let the wheel move only the cursor, m.cursor += dy * 3, and the list follows it as it does the arrow keys.

Items are followed from frame to frame by their index, so mouse handlers and hover styles stay with an item as the list scrolls.

Focus items

An ID of your Focus's type and Focusable() on the list make the whole list one stop in the tab order. To make items focusable instead, give each its own ID, such as from its index, and mark it Focusable. Wrap an item in bloom.Auto to add these to a component that isn't a node; see Place components you're given:

type rowID int // the ID of item i, for a Focus[rowID]

bloom.List(len(m.items), func(i int) bloom.Child {
	return bloom.Auto(m.items[i]).ID(rowID(i)).Focusable()
})

Only the items on screen are in the frame, so only those are in the tab order, and moving focus doesn't scroll the list. To move through every item, make the list one stop and move a cursor with the arrow keys, which Keep keeps in view.

Show a scrollbar

ScrollbarOf the list's own ID follows it in items, and its OnScroll gets the first item to show, for Offset:

bloom.Box(panel, bloom.List(len(m.items), m.row).Offset(m.offset).ID(paneItems)).
	Edge(bloom.Right, bloom.Stretch, bloom.ScrollbarOf(paneItems).OnScroll(func(first int) tea.Cmd {
		m.offset = first
		return nil
	}))

See Show a scrollbar for how scrollbars look and work.

Lists in components

A component that implements Layouter has no root to ask, so its handlers read the frame from the Context its Layout was given. ctx.Frame() returns the frame on screen when it's called, which is the one the handler's event landed in:

func (p *picker) Layout(ctx bloom.Context) bloom.Child {
	return bloom.List(len(p.items), p.row).Offset(p.offset).Keep(p.cursor).ID(p.id).
		On(on.Scroll(func(_, dy int) tea.Cmd {
			v, _ := ctx.Frame().List(p.id)
			p.offset = v.First
			p.cursor = min(max(p.cursor+dy*3, 0), len(p.items)-1)
			return nil
		}))
}

Select text

Selectable() lets the mouse select text in the list. A selection keeps the items it starts and ends in, so it stays as they scroll away and back, and its text is that of every item it covers: those out of view are built when the text is read, or give their text with ItemText. Dragging past the list's edge scrolls it through its on.Scroll handler. See Selections in a list.

item is also called outside the frame, to read the text of a selection. Until the next frame, it must work for every index the list showed, even if you've since changed m.items.

Last updated on

On this page