Examples

Active contributors: aymanbagabas, meowgorithm, caarlos0, muesli

The examples/ directory is a separate Go module that hosts 66 self-contained demo programs. Each subdirectory contains a single main.go (sometimes with a recorded .gif and .tape). The examples double as Bubble Tea's most extensive integration test: the examples CI job builds all of them on every push.

Why a separate module?

Many examples pull in heavier dependencies (Bubbles, Lip Gloss, Glamour, charm/x packages). Keeping them in their own go.mod means consumers of the library do not transitively depend on those packages.

Catalog

The catalog below mirrors examples/README.md. Each row points to the example's main.go.

Demo	What it shows
simple	Minimal countdown program (the smallest legal Bubble Tea app).
altscreen-toggle	Switching between inline and alt screen at runtime.
chat	Multi-line textarea chat input.
composable-views	Composing two bubble models (spinner + timer).
cursor-style	Custom cursor shapes via View.Cursor.
debounce	Throttling key presses.
doom-fire	A Doom-fire animation in the terminal.
exec	Launching $EDITOR with tea.ExecProcess.
eyes	Following the mouse cursor with eyeballs.
file-picker	Bubble's filepicker component.
focus-blur	Reacting to terminal focus events.
fullscreen	A simple fullscreen app.
glamour	Markdown rendering inside a viewport.
help	Bubbles' help component for keymap displays.
http	Making an HTTP call from a Cmd.
isbn-form	A multi-step form using textinput.
keyboard-enhancements	Kitty / modify-other-keys protocol demo.
list-default, list-fancy, list-simple	Three styles of Bubbles' list.
mouse	Reacting to mouse events.
package-manager	Using tea.Println to log progress while a spinner runs.
pager	A less-like pager.
paginator	Paginated list rendering.
pipe	Reading initial state from a shell pipe.
prevent-quit	Filtering QuitMsg with tea.WithFilter.
print-key	Inspecting raw key events.
progress-animated, progress-bar, progress-download, progress-static	Variations on the progress bubble.
query-term	Demonstrating terminal capability queries (RequestCapability, etc.).
realtime	Pushing messages from a Go channel into Update.
result	A choice menu that returns the selected item.
send-msg	Custom tea.Msg types and Program.Send.
sequence	tea.Sequence for ordered command chains.
set-terminal-color	Setting View.ForegroundColor / BackgroundColor.
set-window-title	Setting View.WindowTitle.
space	Asteroid-shooter-style game.
spinner, spinners	Bubbles' spinner.
splash	A minimal animated splash screen.
split-editors	Two textareas side-by-side with focus switching.
stopwatch	Bubbles' stopwatch.
suspend	Handling tea.Suspend and Ctrl+Z.
table, table-resize	Bubbles' table.
tabs	Tabbed navigation styled with Lip Gloss.
textarea	Bubbles' multi-line editor.
textinput, textinputs	Bubbles' single-line input.
timer	Bubbles' timer.
tui-daemon-combo	A program that runs as a TUI when stdout is a TTY and as a daemon otherwise (using WithoutRenderer).
vanish	Removing a rendered region by emptying the view content.
views	Switching between multiple top-level views.
window-size	Reacting to WindowSizeMsg.
canvas, cellbuffer, colorprofile, capability, clickable, dynamic-textarea	Smaller demos of specialized features.

Run any one with:

cd examples
go run ./<name>

CI smoke test

.github/workflows/build.yml's build-examples job builds the entire examples/ module on every PR (skipping dependabot-only PRs to save minutes). If a refactor breaks an example, the build turns red. This is by far the most thorough integration-test net the project has.

Asset workflow

Most examples have a .tape file (a VHS script) that produces the corresponding .gif. New examples are encouraged to include a tape and a gif; the recipe is documented in the vhs repo.

Related pages

• Tutorials — the annotated grocery-list tutorial.
• Architecture — to understand the moving parts each example demonstrates.