# charmbracelet/bubbles architecture

> Architecture diagram of the GitHub repository charmbracelet/bubbles, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/charmbracelet/bubbles
- Repository: https://github.com/charmbracelet/bubbles

## Overview

Bubbles is a Go library of reusable Bubble Tea terminal UI primitives, rather than a standalone application. A consuming application supplies state and messages to a component, handles its updates, and displays the rendered view. The graph preserves the README’s input, browsing, navigation, feedback, timing, and help capabilities, with selected internal composition shown where the source index or excerpts support it. Relationships involving unsampled components are limited to documented capabilities; no application-level orchestration is inferred.

Main entry points: [`list/list.go`](https://github.com/charmbracelet/bubbles/blob/main/list/list.go) (List browser), [`textarea/textarea.go`](https://github.com/charmbracelet/bubbles/blob/main/textarea/textarea.go) (Text area), [`help/help.go`](https://github.com/charmbracelet/bubbles/blob/main/help/help.go) (Help view), [`tree/tree.go`](https://github.com/charmbracelet/bubbles/blob/main/tree/tree.go) (Tree view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Text input"]
  node_textinput["Text input<br/>[textinput.go]"]
  node_textarea["Text area<br/>[textarea.go]"]
  node_cursor["Cursor<br/>[cursor.go]"]
end

subgraph group_browse["Browsing and navigation"]
  node_list["List browser<br/>[list.go]"]
  node_listdelegate["List delegate<br/>[defaultitem.go]"]
  node_filepicker["File picker<br/>[filepicker.go]"]
  node_table["Table<br/>[table.go]"]
  node_tree["Tree view<br/>[tree.go]"]
  node_treenode["Tree node<br/>[node.go]"]
  node_viewport["Viewport<br/>[viewport.go]"]
  node_paginator["Paginator<br/>[paginator.go]"]
end

subgraph group_feedback["Feedback and timing"]
  node_progress["Progress meter<br/>[progress.go]"]
  node_spinner["Spinner<br/>[spinner.go]"]
  node_timer["Countdown timer<br/>[timer.go]"]
  node_stopwatch["Stopwatch<br/>[stopwatch.go]"]
end

subgraph group_shared["Shared UI support"]
  node_help["Help view<br/>[help.go]"]
  node_key["Key bindings<br/>[key.go]"]
  node_memoization["Memoization<br/>[memoization.go]"]
  node_runeutil["Rune utilities<br/>[runeutil.go]"]
end

node_app(("Bubble Tea app"))

node_app -->|"uses input"| node_textinput
node_app -->|"uses input"| node_textarea
node_app -->|"uses browser"| node_list
node_app -->|"uses picker"| node_filepicker
node_app -->|"uses table"| node_table
node_app -->|"uses tree"| node_tree
node_app -->|"uses viewport"| node_viewport
node_app -->|"uses pagination"| node_paginator
node_app -->|"uses progress"| node_progress
node_app -->|"uses spinner"| node_spinner
node_app -->|"uses timer"| node_timer
node_app -->|"uses stopwatch"| node_stopwatch
node_app -->|"uses help"| node_help
node_app -->|"configures keys"| node_key
node_textinput -->|"uses cursor"| node_cursor
node_textinput -->|"uses utilities"| node_runeutil
node_textarea -->|"creates cursor"| node_cursor
node_textarea -->|"sets content"| node_viewport
node_textarea -->|"caches wraps"| node_memoization
node_textarea -->|"uses utilities"| node_runeutil
node_list -->|"creates spinner"| node_spinner
node_list -->|"creates filter"| node_textinput
node_list -->|"renders pages"| node_paginator
node_list -->|"builds help"| node_help
node_list -->|"uses delegate"| node_listdelegate
node_filepicker -->|"matches keys"| node_key
node_table -->|"renders rows"| node_viewport
node_table -->|"creates help"| node_help
node_tree -->|"operates on nodes"| node_treenode
node_tree -->|"uses viewport"| node_viewport
node_tree -->|"creates help"| node_help
node_help -->|"renders bindings"| node_key

click node_textinput "https://github.com/charmbracelet/bubbles/blob/main/textinput/textinput.go"
click node_textarea "https://github.com/charmbracelet/bubbles/blob/main/textarea/textarea.go"
click node_cursor "https://github.com/charmbracelet/bubbles/blob/main/cursor/cursor.go"
click node_list "https://github.com/charmbracelet/bubbles/blob/main/list/list.go"
click node_listdelegate "https://github.com/charmbracelet/bubbles/blob/main/list/defaultitem.go"
click node_filepicker "https://github.com/charmbracelet/bubbles/blob/main/filepicker/filepicker.go"
click node_table "https://github.com/charmbracelet/bubbles/blob/main/table/table.go"
click node_tree "https://github.com/charmbracelet/bubbles/blob/main/tree/tree.go"
click node_treenode "https://github.com/charmbracelet/bubbles/blob/main/tree/node.go"
click node_viewport "https://github.com/charmbracelet/bubbles/blob/main/viewport/viewport.go"
click node_paginator "https://github.com/charmbracelet/bubbles/blob/main/paginator/paginator.go"
click node_progress "https://github.com/charmbracelet/bubbles/blob/main/progress/progress.go"
click node_spinner "https://github.com/charmbracelet/bubbles/blob/main/spinner/spinner.go"
click node_timer "https://github.com/charmbracelet/bubbles/blob/main/timer/timer.go"
click node_stopwatch "https://github.com/charmbracelet/bubbles/blob/main/stopwatch/stopwatch.go"
click node_help "https://github.com/charmbracelet/bubbles/blob/main/help/help.go"
click node_key "https://github.com/charmbracelet/bubbles/blob/main/key/key.go"
click node_memoization "https://github.com/charmbracelet/bubbles/blob/main/internal/memoization/memoization.go"
click node_runeutil "https://github.com/charmbracelet/bubbles/blob/main/internal/runeutil/runeutil.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_textinput,node_textarea,node_cursor toneBlue
class node_list,node_listdelegate,node_filepicker,node_table,node_tree,node_treenode,node_viewport,node_paginator toneAmber
class node_progress,node_spinner,node_timer,node_stopwatch toneMint
class node_help,node_key,node_memoization,node_runeutil toneRose
class node_app toneIndigo
```

## Components

### Text input

- [Text input](https://github.com/charmbracelet/bubbles/blob/main/textinput/textinput.go): `textinput/textinput.go`
- [Text area](https://github.com/charmbracelet/bubbles/blob/main/textarea/textarea.go): `textarea/textarea.go`
- [Cursor](https://github.com/charmbracelet/bubbles/blob/main/cursor/cursor.go): `cursor/cursor.go`

### Browsing and navigation

- [List browser](https://github.com/charmbracelet/bubbles/blob/main/list/list.go): `list/list.go`
- [List delegate](https://github.com/charmbracelet/bubbles/blob/main/list/defaultitem.go): `list/defaultitem.go`
- [File picker](https://github.com/charmbracelet/bubbles/blob/main/filepicker/filepicker.go): `filepicker/filepicker.go`
- [Table](https://github.com/charmbracelet/bubbles/blob/main/table/table.go): `table/table.go`
- [Tree view](https://github.com/charmbracelet/bubbles/blob/main/tree/tree.go): `tree/tree.go`
- [Tree node](https://github.com/charmbracelet/bubbles/blob/main/tree/node.go): `tree/node.go`
- [Viewport](https://github.com/charmbracelet/bubbles/blob/main/viewport/viewport.go): `viewport/viewport.go`
- [Paginator](https://github.com/charmbracelet/bubbles/blob/main/paginator/paginator.go): `paginator/paginator.go`

### Feedback and timing

- [Progress meter](https://github.com/charmbracelet/bubbles/blob/main/progress/progress.go): `progress/progress.go`
- [Spinner](https://github.com/charmbracelet/bubbles/blob/main/spinner/spinner.go): `spinner/spinner.go`
- [Countdown timer](https://github.com/charmbracelet/bubbles/blob/main/timer/timer.go): `timer/timer.go`
- [Stopwatch](https://github.com/charmbracelet/bubbles/blob/main/stopwatch/stopwatch.go): `stopwatch/stopwatch.go`

### Shared UI support

- [Help view](https://github.com/charmbracelet/bubbles/blob/main/help/help.go): `help/help.go`
- [Key bindings](https://github.com/charmbracelet/bubbles/blob/main/key/key.go): `key/key.go`
- [Memoization](https://github.com/charmbracelet/bubbles/blob/main/internal/memoization/memoization.go): `internal/memoization/memoization.go`
- [Rune utilities](https://github.com/charmbracelet/bubbles/blob/main/internal/runeutil/runeutil.go): `internal/runeutil/runeutil.go`

### Other components

- **Bubble Tea app**

## Connections

- Bubble Tea app → Text input: uses input (evidence: `README.md`)
- Bubble Tea app → Text area: uses input (evidence: `README.md`)
- Bubble Tea app → List browser: uses browser (evidence: `README.md`)
- Bubble Tea app → File picker: uses picker (evidence: `README.md`)
- Bubble Tea app → Table: uses table (evidence: `README.md`)
- Bubble Tea app → Tree view: uses tree (evidence: `README.md`)
- Bubble Tea app → Viewport: uses viewport (evidence: `README.md`)
- Bubble Tea app → Paginator: uses pagination (evidence: `README.md`)
- Bubble Tea app → Progress meter: uses progress (evidence: `README.md`)
- Bubble Tea app → Spinner: uses spinner (evidence: `README.md`)
- Bubble Tea app → Countdown timer: uses timer (evidence: `README.md`)
- Bubble Tea app → Stopwatch: uses stopwatch (evidence: `README.md`)
- Bubble Tea app → Help view: uses help (evidence: `README.md`)
- Bubble Tea app → Key bindings: configures keys (evidence: `README.md`)
- Text input → Cursor: uses cursor (evidence: `textinput/textinput.go`)
- Text input → Rune utilities: uses utilities (evidence: `textinput/textinput.go`)
- Text area → Cursor: creates cursor (evidence: `textarea/textarea.go`)
- Text area → Viewport: sets content (evidence: `textarea/textarea.go`)
- Text area → Memoization: caches wraps (evidence: `textarea/textarea.go`)
- Text area → Rune utilities: uses utilities (evidence: `textarea/textarea.go`)
- List browser → Spinner: creates spinner (evidence: `list/list.go`)
- List browser → Text input: creates filter (evidence: `list/list.go`)
- List browser → Paginator: renders pages (evidence: `list/list.go`)
- List browser → Help view: builds help (evidence: `list/list.go`)
- List browser → List delegate: uses delegate (evidence: `list/defaultitem.go`)
- File picker → Key bindings: matches keys (evidence: `filepicker/filepicker.go`)
- Table → Viewport: renders rows (evidence: `table/table.go`)
- Table → Help view: creates help (evidence: `table/table.go`)
- Tree view → Tree node: operates on nodes (evidence: `tree/tree.go`)
- Tree view → Viewport: uses viewport (evidence: `tree/tree.go`)
- Tree view → Help view: creates help (evidence: `tree/tree.go`)
- Help view → Key bindings: renders bindings (evidence: `help/help.go`)
