Nodes and options

A compact reference of bloom's nodes, slot and layer options, Root options, and anim options, with links to the full API documentation.

This page lists what's available, grouped by what it's for. The full documentation, with every method's details, is on pkg.go.dev.

Nodes

Function	Makes
`Row(children...)`	children left to right
`Column(children...)`	children top to bottom
`Grid(cols, children...)`	equal-width columns, filled row by row
`Wrap(children...)`	children flowing onto new lines at their natural sizes
`Text(s)`	a string, optionally styled
`Marquee(s, phase)`	one line that scrolls, or is cut short, when it doesn't fit
`Skeleton(lines...)`	placeholder bars for content still loading, a line for each width, 0 for a blank line
`Box(style, child)`	a Lip Gloss frame around a child
`Centered(child)`	a child at its natural size in the middle of its space
`Scroll(child, offset)`	a child shown from row `offset`
`Overlay(base, layers...)`	layers drawn over a base
`Layer(child)`	a layer for an overlay, centered at its natural size
`Transition(t, child, effects...)`	a child drawn with effects at progress `t`
`Present(p, child, effects...)`	a child shown only while a presence is visible
`Drawable(d)`	an Ultraviolet `Drawable`, painting cells directly

Any value with a View() string method can also be a child.

Container options

Method	On	Does
`Gap(n)`	`Row`, `Column`	`n` cells between children
`Gap(x, y)`	`Grid`, `Wrap`	space between columns and between rows
`Align(a)`	`Row`, `Column`	cross-axis placement of children: `Stretch` (default), `Start`, `Center`, `End`
`Justify(j)`	`Row`, `Column`	main-axis placement when nothing grows: `flex.Start`, `Center`, `End`, `SpaceBetween`, `SpaceAround`, `SpaceEvenly`

Slots

Function	Size
`Fixed(n, child)`	exactly `n` cells; a `nil` child is empty space
`Auto(child)`	the child's natural size
`Fill(child)`	an equal share of what's left
`Grow(weight, child)`	a weighted share of what's left
`Percent(p, child)`	`p`% of the container
`Space()`	empty space that fills what's left

Method	Does
`Min(n)`, `Max(n)`	clamp the size on the main axis
`Collapsible(priority)`	allow dropping the slot when minimums don't fit, lowest priority first
`Align(a)`	this slot's cross-axis placement
`ID(id)`	the ID for focus, layout animation, and `Frame.Rect`
`On(handlers...)`	mouse handlers from the `on` package
`Focusable()`	a stop in the focus order
`Scope()`	a focus scope, for `Focus.Within` and `Focus.Push`
`Animate(opts...)`	glide to new positions and sizes; needs an ID and a `Root`

Text

Method	Does
`Style(style)`	render with a Lip Gloss style at the node's size, wrapping long lines
`Truncate()`	one line, cut short with "…"
`Cursor(c)`	show the terminal cursor at `c`, relative to the node
`HoverStyle(style)`	render with `style` while the pointer is over the node
`ID(id)`, `Focusable()`, `On(handlers...)`	as for slots

Boxes, rows, columns, grids, and wraps have ID(id) and On(handlers...) too, and boxes have HoverStyle(style) for their frame.

Marquee has Style(style) and Gap(s), the text shown between loops. Skeleton has Style(style), which colors the bars, and Shimmer(phase), which sweeps a band of light across them.

Layers

Method	Does
`Anchor(x, y)`	place on each axis: `Start`, `Center` (default), `End`
`AnchorTo(id, side)`	place against a side of another node
`Offset(x, y)`	move from where it's anchored
`Size(w, h)`	set the size; zero uses the natural size
`Margin(n)`	stay `n` cells from the screen's edges
`Modal()`	take every mouse event from what's beneath, and be a focus scope
`Backdrop(effects...)`	apply effects to everything beneath
`Shadow(x, y, effects...)`	apply effects beneath, offset like a drop shadow
`Presence(p, effects...)`	show while a presence is visible, with effects
`Transition(t, effects...)`	draw with effects at progress `t`
`ID(id)`	the ID for focus, anchoring, layout animation, and `Frame.Rect`
`On(handlers...)`	mouse handlers; `on.ClickOutside` runs for a modal layer's backdrop
`Animate(opts...)`	glide to new positions and sizes; needs an ID and a `Root`

Root

	Does
`bloom.New(opts...)`	make a root; keep it in your model by pointer
`ui.Init()`	ask the terminal for its colors; return from `Init`
`ui.Update(msg)`	hear the terminal, run layout animation, and keep hover up to date; pass every message, return the command
`ui.View(w, h, tree)`	lay out, draw, and return a `tea.View` that runs mouse handlers
`ui.Render(w, h, tree)`	lay out and draw to a string; a height of zero uses the natural height
`ui.Frame()`	the geometry of the last frame drawn
`ui.Click(id)`, `ui.ClickAt(x, y)`	run the handlers for a click, for tests

Root options

Option	Default	Sets
`WithColors(fg, bg)`	white on black	the terminal colors effects blend with, until the terminal reports its own
`WithFPS(n)`	60	the frame rate of layout animation
`WithUnfocusedFPS(n)`	10	the frame rate of layout animation while the terminal isn't focused
`WithWidthMethod(m)`	`ansi.GraphemeWidth`	how character widths are measured; must match the terminal
`WithClock(now)`	`time.Now`	the clock for layout animation and double clicks, for tests
`WithFocus(&m.focus)`	none	the focus that clicks move, before handlers run

Geometry and input

	Does
`Solve(tree, w, h)`	lay out without drawing, and return the `*Frame`
`Render(tree, w, h)`	lay out and draw to a string, without a root
`frame.Rect(id)`	where a node went, and whether it's in the frame
`frame.Hit(x, y)`	the IDs of the nodes at a point, outermost first
`ThrottleMouse(every)`	a `tea.WithFilter` filter that drops wheel and motion events that come too fast
`Focus[K]` methods	`Set`, `Clear`, `Is`, `Current`, `Next`, `Prev`, `Update`, `Push`, `Pop`, `Scope`, `Within`; `K` is the type of the IDs focus moves between

Mouse handlers

From github.com/lrstanley/bloom/on, for On(...):

Handler	Runs on
`on.Click(fn)`, `on.RightClick(fn)`, `on.MiddleClick(fn)`	a click with that button, when it comes up over the node
`on.DoubleClick(fn)`	the second of two left clicks within 400ms
`on.Press(fn)`	a left click, or enter or space while focused
`on.ClickAt(fn)`	a left click, with an `on.Event` holding where
`on.Scroll(fn)`	the wheel, as `dx, dy`
`on.Hover(fn)`	the pointer moving onto or off the node
`on.Drag(fn)`	a left-button drag that starts on the node, until the button comes up
`on.ClickOutside(fn)`	a button going down anywhere else; a modal layer's backdrop
`on.Mouse(fn)`	every mouse event over the node
`on.Msg(msg)`	a handler function that sends `msg` to `Update`

Component interfaces: Measurer reports a natural size, and Layouter builds a layout for the space given.

Animation options

For anim.NewValue, anim.NewPresence, anim.NewLoop, Sequence.With, anim.To, and Animate:

Option	Default	Sets
`Duration(d)`	250ms	how long easing to a target takes
`Ease(e)`	`OutCubic`	the easing curve
`Spring(frequency, damping)`		move like a spring instead of easing
`FPS(n)`	60	frames requested while animating
`UnfocusedFPS(n)`	10	frames requested while the terminal isn't focused
`Clock(now)`	`time.Now`	the source of time, for tests

Easings: Linear, InQuad, OutQuad, InOutQuad, OutCubic, InOutCubic, OutBack, or any func(float64) float64.

Sequence steps: To(target, opts...), Hold(d), Jump(target).

Nodes and options

NodesCopy Anchor Link

Container optionsCopy Anchor Link

SlotsCopy Anchor Link

TextCopy Anchor Link

LayersCopy Anchor Link

RootCopy Anchor Link

Root optionsCopy Anchor Link

Geometry and inputCopy Anchor Link

Mouse handlersCopy Anchor Link

Animation optionsCopy Anchor Link

On this page