# bloom

> bloom is a Go library for Bubble Tea (charm.land/bubbletea/v2) programs. A view is described each frame as a tree of nodes (rows, columns, grids, boxes, and overlays with layers such as dialogs, dropdowns, and toasts), which bloom lays out, composites, animates, and routes mouse and focus input for. Its packages are bloom (layout, layers, input), anim (springs, eased values, presences, and sequences kept in the model), and fx (cell effects used as transitions and backdrops).

Import path: github.com/lrstanley/bloom. Every page below links to its markdown version; the whole site is also available as a single file at https://bloomfx.dev/llms-full.txt.


- **Getting started**
- [Introduction](https://bloomfx.dev/getting-started/introduction.md): What bloom is, what it takes off your hands in a Bubble Tea program, and how its packages fit together.
- [Installation](https://bloomfx.dev/getting-started/installation.md): Add bloom to a Go module, and the versions of Go, Bubble Tea, and Lip Gloss it works with.
- [Build your first layout](https://bloomfx.dev/getting-started/first-layout.md): A step-by-step tutorial that builds a small notes app with a sidebar, a reader, a status bar, and clickable items.
- [Add a dialog and a toast](https://bloomfx.dev/getting-started/dialogs-and-toasts.md): A tutorial that adds a confirmation dialog with a dimmed backdrop, keyboard focus, and an auto-hiding toast notification to the notes app.

- **Layout**
- [Sizing with slots](https://bloomfx.dev/layout/slots.md): Control how children of a row or column share space with Fixed, Auto, Fill, Grow, Percent, Min, Max, and Space.
- [Responsive layouts](https://bloomfx.dev/layout/responsive.md): Adapt a layout to the terminal's size by collapsing panels by priority, using percentages, and building layouts for the space a component is given.
- [Text, boxes, and alignment](https://bloomfx.dev/layout/text-and-boxes.md): Show styled and truncated text, draw Lip Gloss borders around nodes, center things, and control alignment, justification, and gaps.
- [Grids and wrapping](https://bloomfx.dev/layout/grids-and-wrapping.md): Lay children out in equal-width columns with Grid, or flow them onto as many lines as they need with Wrap.
- [Scrolling and sizing in Update](https://bloomfx.dev/layout/scrolling.md): Scroll content that is taller than its space, and use Solve to find a node's size in Update for paging and for components that need their size up front.
- [Using Bubbles components](https://bloomfx.dev/layout/bubbles-components.md): Place Bubbles components such as viewport, textinput, list, and table in a bloom layout, give them the size they need, and show the real terminal cursor.

- **Layers**
- [Dialogs and modals](https://bloomfx.dev/layers/dialogs.md): Show dialogs over the rest of the screen with Overlay and Layer, make them modal, dim or recolor what's beneath, add shadows, and stack them.
- [Dropdowns and popovers](https://bloomfx.dev/layers/dropdowns.md): Attach a layer to another node with AnchorTo, for autocomplete suggestions, menus, tooltips, and popovers that follow what they belong to.
- [Toast notifications](https://bloomfx.dev/layers/toasts.md): Show a notification in a corner of the screen that animates in and hides itself after a while, and stack several of them.

- **Input**
- [Mouse events](https://bloomfx.dev/input/mouse.md): Attach click, wheel, hover, and drag handlers to the nodes they're about with the on package, change state directly or send a message, and use hover styles, drags, and modal layers.
- [Focus and keyboard navigation](https://bloomfx.dev/input/focus.md): Track keyboard focus with bloom.Focus, move it with tab and clicks, press buttons with enter, confine it to dialogs and panels with scopes, and show the terminal cursor.

- **Motion**
- [Animating values](https://bloomfx.dev/motion/animating-values.md): Keep animations in your model with anim.Value, anim.Presence, and anim.Sequence, choose between easing and springs, and drive them with messages.
- [Transitions](https://bloomfx.dev/motion/transitions.md): Animate nodes and layers in and out with effects, combine and sequence effects, and open a dialog from the button that was pressed.
- [Layout animation](https://bloomfx.dev/motion/layout-animation.md): Make slots and layers move and resize smoothly whenever the layout changes, with Animate, and no animation state in your model.
- [Feedback effects](https://bloomfx.dev/motion/feedback-effects.md): Shake rejected input, show skeleton placeholders that shimmer while loading, roll changing numbers, burst confetti, glitch a badge, spotlight a tour step, and scroll text that doesn't fit.
- [Custom effects](https://bloomfx.dev/motion/custom-effects.md): Write your own cell effects with the fx.Effect interface and canvas.Surface, and draw directly onto cells with Drawable.

- **Concepts**
- [How layout works](https://bloomfx.dev/concepts/how-layout-works.md): The model behind bloom's layout - constraints go down, sizes come up, parents place - and why the tree is rebuilt every frame.
- [Rendering and performance](https://bloomfx.dev/concepts/rendering.md): How bloom turns a tree into a frame - caching, compositing, effects, and mouse routing - and what to keep in mind for smooth animation.

- **Reference**
- [Effects](https://bloomfx.dev/reference/effects.md): Every effect in the fx package, its fields, and whether it suits a transition, a backdrop, or feedback.
- [Nodes and options](https://bloomfx.dev/reference/options.md): A compact reference of bloom's nodes, slot and layer options, Root options, and anim options, with links to the full API documentation.

- **Resources**
- [Examples](https://bloomfx.dev/resources/examples.md): Runnable example programs in the bloom repository, what each one shows, and how to run them.
- [Testing](https://bloomfx.dev/resources/testing.md): Test bloom layouts with Render and Solve in plain unit tests, and test whole programs end to end with steep.
- [Related libraries](https://bloomfx.dev/resources/related-libraries.md): Libraries that work well alongside bloom, for theming, testing, and the rest of a Bubble Tea program.
- [Troubleshooting](https://bloomfx.dev/resources/troubleshooting.md): Fixes for common problems - a blank screen, clicks that don't arrive or arrive twice, animations that don't move, text that doesn't wrap, and more.

## Optional

- [bloom API reference](https://pkg.go.dev/github.com/lrstanley/bloom): Go package documentation for bloom
- [anim API reference](https://pkg.go.dev/github.com/lrstanley/bloom/anim): Go package documentation for bloom/anim
- [fx API reference](https://pkg.go.dev/github.com/lrstanley/bloom/fx): Go package documentation for bloom/fx
- [Bubble Tea](https://github.com/charmbracelet/bubbletea): the TUI framework bloom builds on
- [Lip Gloss](https://github.com/charmbracelet/lipgloss): the styling library bloom's boxes and text use
- [Source and examples](https://github.com/lrstanley/bloom): the repository, including runnable programs in _examples