bubbles Documentation

Technical Documentation: charmbracelet/bubbles

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Bubbles

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

[!TIP]

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

Spinner Copy Chapter

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 Copy Chapter

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 Copy Chapter

A text area field, akin to an <textarea /> 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 Copy Chapter

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

• Example code, countries and populations

Progress Copy Chapter

A simple, customizable progress meter, with optional animation via
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

Paginator Copy Chapter

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 Copy Chapter

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 for ANSI-aware
indenting and text wrapping.

List Copy Chapter

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 Copy Chapter

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 Copy Chapter

A simple, flexible component for counting down. The update frequency and output
can be customized as you like.

• Example code

Stopwatch Copy Chapter

A simple, flexible component for counting up. The update frequency and output
can be customized as you see fit.

• Example code

Help Copy Chapter

A customizable horizontal mini help view that automatically generates itself
from your keybindings. It features single and multi-line modes, which the user
can optionally toggle between. It will truncate gracefully if the terminal is
too wide for the content.

• Example code

Key Copy Chapter

A non-visual component for managing keybindings. It’s useful for allowing users
to remap keybindings as well as generating help views corresponding to your
keybindings.

type KeyMap struct {
    Up key.Binding
    Down key.Binding
}

var DefaultKeyMap = KeyMap{
    Up: key.NewBinding(
        key.WithKeys("k", "up"),        // actual keybindings
        key.WithHelp("↑/k", "move up"), // corresponding help text
    ),
    Down: key.NewBinding(
        key.WithKeys("j", "down"),
        key.WithHelp("↓/j", "move down"),
    ),
}

func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyPressMsg:
        switch {
        case key.Matches(msg, DefaultKeyMap.Up):
            // The user pressed up
        case key.Matches(msg, DefaultKeyMap.Down):
            // The user pressed down
        }
    }
    return m, nil
}

There’s more where that came from Copy Chapter

To check out community-maintained Bubbles see Charm & Friends.
Made a cool Bubble that you want to share? PRs are welcome!

Contributing Copy Chapter

See contributing.

Feedback Copy Chapter

We’d love to hear your thoughts on this project. Feel free to drop us a note!

• Twitter
• The Fediverse
• Discord

License Copy Chapter

MIT

Part of Charm.

Charm热爱开源 • Charm loves open source

Overview (`list/README.md`) Copy Section

Frequently Asked Questions

These are some of the most commonly asked questions regarding the list bubble.

Adding Custom Items Copy Chapter

There are a few things you need to do to create custom items. First off, they
need to implement the list.Item and list.DefaultItem interfaces.

// Item is an item that appears in the list.
type Item interface {
	// FilterValue is the value we use when filtering against this item when
	// we're filtering the list.
	FilterValue() string
}

// DefaultItem describes an item designed to work with DefaultDelegate.
type DefaultItem interface {
	Item
	Title() string
	Description() string
}

You can see a working example in our Kancli project built
explicitly for a tutorial on lists and composite views in Bubble Tea.

VIDEO

Customizing Styles Copy Chapter

Rendering (and behavior) for list items is done via the
ItemDelegate
interface. It can be a little confusing at first, but it allows the list to be
very flexible and powerful.

If you just want to alter the default style you could do something like:

import "github.com/charmbracelet/bubbles/v2/list"

// Create a new default delegate
d := list.NewDefaultDelegate()

// Change colors
c := lipgloss.Color("#6f03fc")
d.Styles.SelectedTitle = d.Styles.SelectedTitle.Foreground(c).BorderLeftForeground(c)
d.Styles.SelectedDesc = d.Styles.SelectedTitle.Copy() // reuse the title style here

// Initailize the list model with our delegate
width, height := 80, 40
l := list.New(listItems, d, width, height)

// You can also change the delegate on the fly
l.SetDelegate(d)

This code would replace this line in the list-default
example.

For full control over the way list items are rendered you can also define your
own ItemDelegate too (example).

--- METRICS ---

• Files Extracted: 2
• Estimated Token Budget: ~2738 tokens
• Canonical Reference: https://codewiki.google/github.com/charmbracelet/bubbles