charmbracelet /bubbles

TUI components for Bubble Tea 🫧

★ 9,055⑂ 486👁 27⑃ 699● 279▤ 38
GoMITCreated 2020-01-18
More from this author
Download: v2.2.1v2.2.1 ↓2.2.12026-08-24
+3
Daily
9,055
stars
486
forks
27
watchers
699
prs
279
issues
38
releases

README

Bubbles








Primitives for Bubble Tea
applications. These components are used in production in [Crush][crush], and [many other applications][otherstuff].

 [!TIP]

 Upgrading from v1? Check out the upgrade guide, or
 point your LLM at it and let it go to town.

[crush]: https://github.com/charmbracelet/crush
[otherstuff]: https://github.com/charmbracelet/bubbletea/bubble-tea-in-the-wild

 Spinner



A spinner, useful for indicating that some kind an operation is happening.
There are a couple default ones, but you can also pass your own ”frames.”

- Example code, basic spinner
- Example code, various spinners

 Text Input



A text input field, akin to an  in HTML. Supports unicode,
pasting, in-place scrolling when the value exceeds the width of the element and
the common, and many customization options.

- Example code, one field
- Example code, many fields

 Text Area



A text area field, akin to an  in HTML. Allows for input that
spans multiple lines. Supports unicode, pasting, vertical scrolling when the
value exceeds the width and height of the element, and many customization
options.

- Example code, chat input
- Example code, story time input

 Table



A component for displaying and navigating tabular data (columns and rows).
Supports vertical scrolling and many customization options.

- Example code, countries and populations

 Progress



A simple, customizable progress meter, with optional animation via
[Harmonica][harmonica]. Supports solid and gradient fills. The empty and filled
runes can be set to whatever you'd like. The percentage readout is customizable
and can also be omitted entirely.

- Animated example
- Static example

[harmonica]: https://github.com/charmbracelet/harmonica

 Paginator



A component for handling pagination logic and optionally drawing pagination UI.
Supports "dot-style" pagination (similar to what you might see on iOS) and
numeric page numbering, but you could also just use this component for the
logic and visualize pagination however you like.

- Example code

 Viewport



A viewport for vertically scrolling content. Optionally includes standard
pager keybindings and mouse wheel support. A high performance mode is available
for applications which make use of the alternate screen buffer.

- Example code

This component is well complemented with [Reflow][reflow] for ANSI-aware
indenting and text wrapping.

[reflow]: https://github.com/muesli/reflow

 List



A customizable, batteries-included component for browsing a set of items.
Features pagination, fuzzy filtering, auto-generated help, an activity spinner,
and status messages, all of which can be enabled and disabled as needed.
Extrapolated from [Glow][glow].

- Example code, default list
- Example code, simple list
- Example code, all features

 File Picker



A customizable component for picking a file from the file system. Navigate
through directories and select files, optionally limit to certain file
extensions.

- Example code

 Timer

A simple,

Top issues

Discussions

Latest release

v2.2.1 v2.2.1 2026-08-24
Tiny Monday bugfix

Textarea element had a bug, where you used to be able to go 1 word backwards, even if there was nothing, which resulted in the whole TUI freezing. It was now fixed by @OxQuasar!

 Changelog
 Fixed
 f6134114d735cf40e95c15ff62e7359e46d04fc9: fix(textarea): stop word-left at input boundary (1036) (@OxQuasar)
 Docs
 87d445838781700cb25e3fc3a6b26006eab97b41: docs: update godoc link in readme to new package (@meowgorithm)
 Other stuff
 10489b5fafe92bfaea873297cab8ac8b5c5237f4: readme: drop tree section for now (@meowgorithm)
 490948109eb4731927ba2f4cd464d8175a9630d7: v

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON