Bubbles Component Catalog

All components live under charm.land/bubbles/v2/<package>.

spinner

Animated loading indicator with preset and custom frame sets.

Key Types:

Model - component state (Spinner, Style fields)
Spinner - frame definition (Frames []string, FPS time.Duration)
TickMsg - animation frame message

Presets: Line, Dot, MiniDot, Jump, Pulse, Points, Globe, Moon, Monkey, Meter, Hamburger, Ellipsis

Constructor:

s := spinner.New(spinner.WithSpinner(spinner.Dot), spinner.WithStyle(style))

Start: Return m.spinner.Tick from your Init().

Usage:

m.spinner, cmd = m.spinner.Update(msg)
view := m.spinner.View()

textinput

Single-line text input with cursor, placeholder, validation, echo modes, and autocomplete suggestions.

Key Types:

Model - component state
KeyMap - customizable keybindings
EchoMode - EchoNormal, EchoPassword, EchoNone
ValidateFunc - func(string) error
Styles - focused/blurred state styles

Constructor:

ti := textinput.New()
ti.Placeholder = "Type here..."
ti.CharLimit = 100
ti.SetWidth(40)

Key Methods:

Focus() tea.Cmd / Blur() - focus management
Value() string / SetValue(string) - get/set content
SetSuggestions([]string) - autocomplete suggestions (set ShowSuggestions = true)
SetStyles(Styles) - apply styles
Validate ValidateFunc - assign validation function, errors go to Err field

textarea

Multi-line text editor with line numbers, word wrapping, cursor navigation, and viewport scrolling.

Key Types:

Model - component state
KeyMap - extensive keybindings (character/word/line movement, case transforms, transpose)
LineInfo - cursor position metadata

Constructor:

ta := textarea.New()
ta.SetWidth(60)
ta.SetHeight(10)
ta.Placeholder = "Enter text..."
ta.ShowLineNumbers = true

Key Methods:

Focus() tea.Cmd / Blur() - focus management
Value() string / SetValue(string) - get/set content
Line() int / LineCount() int - cursor line info
SetStyles(Styles) - focused/blurred styles

list

Batteries-included list browser with fuzzy filtering, pagination, help, spinner, and status messages.

Key Types:

Model - component state
Item interface - must implement FilterValue() string
ItemDelegate interface - Render, Height, Spacing, Update methods
FilterState - Unfiltered, Filtering, FilterApplied
FilterFunc - custom filter function
Rank - filter match result

Constructor:

items := []list.Item{myItem1, myItem2}
l := list.New(items, myDelegate, width, height)
l.Title = "My List"

Key Methods:

SetItems([]Item) / Items() []Item - manage items
SelectedItem() Item / Index() int - get selection
SetSize(w, h int) - resize
SetFilteringEnabled(bool) - toggle filtering
NewStatusMessage(string) tea.Cmd - show temporary status
SetShowHelp(bool) / SetShowTitle(bool) / SetShowFilter(bool) - toggle UI elements

Built-in Filter: list.DefaultFilter (fuzzy), list.UnsortedFilter

table

Tabular data display with row selection and keyboard navigation.

Key Types:

Model - component state
Row - []string
Column - Title string, Width int
KeyMap - up/down/page/goto keybindings
Styles - Header, Cell, Selected

Constructor:

t := table.New(
    table.WithColumns([]table.Column{
        {Title: "Name", Width: 20},
        {Title: "Age", Width: 5},
    }),
    table.WithRows([]table.Row{
        {"Alice", "30"},
        {"Bob", "25"},
    }),
    table.WithHeight(10),
    table.WithFocused(true),
)

Key Methods:

Focus() / Blur() - focus management
SelectedRow() Row / Cursor() int - get selection
SetRows([]Row) / SetColumns([]Column) - update data
SetWidth(int) / SetHeight(int) - resize
SetCursor(int) - set selection index
FromValues(value, separator string) - parse string data
HelpView() string - render help from keymap
UpdateViewport() - refresh after data changes

viewport

Scrollable content viewer with vertical/horizontal scrolling, soft wrap, mouse wheel, line gutters, and text highlighting.

Key Types:

Model - component state
KeyMap - scroll keybindings (Up/Down/Left/Right/PageUp/PageDown/HalfPageUp/HalfPageDown)
GutterFunc / GutterContext - left gutter rendering (line numbers, etc.)

Constructor:

vp := viewport.New(viewport.WithWidth(80), viewport.WithHeight(24))
vp.SetContent("long text content here...")

Key Methods:

SetContent(string) / GetContent() string - set/get content
SetContentLines([]string) - set content as lines
SetWidth(int) / SetHeight(int) - resize
ScrollDown(n) / ScrollUp(n) / ScrollLeft(n) / ScrollRight(n) - scroll
GotoTop() / GotoBottom() - jump to extremes
AtTop() bool / AtBottom() bool - position checks
ScrollPercent() float64 - scroll progress (0-1)
YOffset() int / SetYOffset(int) - vertical position
SetHighlights([][]int) / HighlightNext() / HighlightPrevious() - search highlighting
EnsureVisible(line, colstart, colend int) - scroll to show position

Fields:

SoftWrap bool - enable word wrap (disables horizontal scroll)
FillHeight bool - pad with empty lines
MouseWheelEnabled bool / MouseWheelDelta int - mouse config
LeftGutterFunc GutterFunc - line number gutter
Style lipgloss.Style - border/padding style
HighlightStyle / SelectedHighlightStyle - search match styles
StyleLineFunc func(int) lipgloss.Style - per-line styling

paginator

Pagination logic and display (dot or numeric style).

Key Types:

Model - component state
Type - Arabic (1/5), Dots (bullet dots)
KeyMap - PrevPage, NextPage

Constructor:

p := paginator.New(paginator.WithPerPage(10), paginator.WithTotalPages(5))

Key Methods:

NextPage() / PrevPage() - navigate
SetTotalPages(itemCount int) int - calculate pages from item count
GetSliceBounds(length int) (start, end int) - get slice indices for current page
ItemsOnPage(totalItems int) int - items on current page
OnFirstPage() bool / OnLastPage() bool - position checks

Fields: Page, PerPage, TotalPages, ActiveDot, InactiveDot, ArabicFormat

progress

Animated progress bar with solid, gradient, and dynamic color fills.

Key Types:

Model - component state
FrameMsg - animation tick
ColorFunc - func(total, current float64) color.Color

Constructor:

p := progress.New(
    progress.WithDefaultBlend(),      // purple-to-pink gradient
    progress.WithWidth(40),
    progress.WithoutPercentage(),
)
// Or solid color:
p := progress.New(progress.WithColors(lipgloss.Color("#FF0000")))
// Or dynamic:
p := progress.New(progress.WithColorFunc(myColorFunc))

Key Methods:

SetPercent(float64) tea.Cmd - animate to percentage (0-1), returns cmd
IncrPercent(float64) tea.Cmd / DecrPercent(float64) tea.Cmd - relative changes
ViewAs(float64) string - static render at given percentage (no animation)
View() string - render current animated state
Percent() float64 - current target percentage
IsAnimating() bool - whether animation is in progress
SetWidth(int) / Width() int - resize
SetSpringOptions(frequency, damping float64) - animation physics

Fields: Full, Empty (runes), FullColor, EmptyColor, ShowPercentage, PercentFormat, PercentageStyle

help

Auto-generated horizontal help view from keybindings. Supports short (single line) and full (multi-column) modes.

Key Types:

Model - component state
KeyMap interface - ShortHelp() []key.Binding, FullHelp() [][]key.Binding
Styles - separate styles for short/full key/desc/separator

Constructor:

h := help.New()
h.SetWidth(80)

Usage:

// Pass your KeyMap implementation
view := h.View(myKeyMap)

// Or render directly
view := h.ShortHelpView(bindings)
view := h.FullHelpView(bindingGroups)

Fields: ShowAll bool (toggle short/full), ShortSeparator, FullSeparator, Ellipsis

filepicker

File system browser for selecting files/directories.

Key Types:

Model - component state
KeyMap - navigation keys (Up/Down/Back/Open/Select/PageUp/PageDown/GoToTop/GoToLast)
Styles - styles for cursor, directory, file, symlink, permissions, etc.

Constructor:

fp := filepicker.New()
fp.CurrentDirectory = "/home/user"
fp.AllowedTypes = []string{".go", ".md"}
fp.DirAllowed = false
fp.FileAllowed = true
fp.ShowHidden = true

Key Methods:

DidSelectFile(msg tea.Msg) (bool, string) - check if user selected a valid file
DidSelectDisabledFile(msg tea.Msg) (bool, string) - check if user tried to select a disallowed file

Fields: CurrentDirectory, AllowedTypes, ShowPermissions, ShowSize, ShowHidden, DirAllowed, FileAllowed, AutoHeight, Path, FileSelected

timer

Countdown timer with configurable interval.

Key Types:

Model - component state
TickMsg - periodic tick (has Timeout bool flag)
TimeoutMsg - sent once when timer expires
StartStopMsg - control message

Constructor:

t := timer.New(30*time.Second, timer.WithInterval(100*time.Millisecond))

Start: Return m.timer.Init() from your Init().

Key Methods:

Start() tea.Cmd / Stop() tea.Cmd / Toggle() tea.Cmd - control
Running() bool / Timedout() bool - state queries
View() string - renders remaining time

Fields: Timeout time.Duration, Interval time.Duration

stopwatch

Count-up timer with start/stop/reset.

Key Types:

Model - component state
TickMsg - periodic tick
StartStopMsg / ResetMsg - control messages

Constructor:

sw := stopwatch.New(stopwatch.WithInterval(100*time.Millisecond))

Start: Return m.stopwatch.Init() from your Init().

Key Methods:

Start() tea.Cmd / Stop() tea.Cmd / Toggle() tea.Cmd / Reset() tea.Cmd - control
Running() bool - state query
Elapsed() time.Duration - get elapsed time
View() string - renders elapsed time

Fields: Interval time.Duration

cursor

Virtual cursor used internally by textinput and textarea. Supports blink, static, and hidden modes.

Key Types:

Model - cursor state
Mode - CursorBlink, CursorStatic, CursorHide
BlinkMsg - blink tick

Constructor:

c := cursor.New()

Key Methods:

Focus() tea.Cmd / Blur() - focus management
SetMode(Mode) tea.Cmd - set cursor behavior
Mode() Mode - get current mode
SetChar(string) - character under cursor
Blink() tea.Cmd - start blink cycle

Fields: Style, TextStyle, BlinkSpeed, IsBlinked

key

Non-visual utility for defining remappable keybindings with help text integration.

Key Types:

Binding - a set of keys with optional help text
BindingOpt - functional option for NewBinding
Help - Key string, Desc string

Constructor:

b := key.NewBinding(
    key.WithKeys("k", "up"),
    key.WithHelp("up/k", "move up"),
)

Key Functions:

key.Matches(key fmt.Stringer, bindings ...Binding) bool - check if key matches any binding

Key Methods on Binding:

Enabled() bool / SetEnabled(bool) - enable/disable
Keys() []string / SetKeys(...string) - get/set keys
Help() Help / SetHelp(key, desc string) - get/set help text
Unbind() - remove all keys and help

runeutil (internal)

Internal sanitizer for cleaning rune input (tab/newline replacement). Not part of the public API.

components.md

Bubbles Component Catalog

spinner

textinput

textarea

list

table

viewport

paginator

progress

help

filepicker

timer

stopwatch

cursor

key

runeutil (internal)