Bubbletea Component Export

Option	Description
Semantic (ANSI 16)	Maps colors to the 16 standard ANSI colors via `lipgloss.Color("1")` etc. Maximum compatibility with all terminals, but limited color accuracy. Best for SSH sessions or legacy terminals.
xterm-256 (wide support)	Uses xterm-256 color codes via `lipgloss.Color("28")` etc. Great balance of color fidelity and compatibility. Works in Terminal.app, iTerm2, Windows Terminal, and most modern terminals.
Hex colors (exact)	Uses exact hex colors via `lipgloss.Color("#RRGGBB")`. Best color accuracy but requires terminal true color support.

Tip

Which should I choose?

Use Semantic if you need to support older terminals or when colors should match the user's terminal theme
Use xterm-256 for the best balance of color fidelity and compatibility
Use Hex only when you know your users have terminals with true color support (iTerm2, Kitty, Alacritty, etc.)

All modes generate dual color dictionaries (COLORS_DARK/COLORS_LIGHT or THEME_DARK/THEME_LIGHT) for runtime theme selection.

Playback Style

Style	Description
Autoplay	Animation starts immediately, no user interaction
Keyboard	User controls with Space (play/pause), R (restart), Q (quit)
API	Programmatic control via model methods

Loop Animation

Option	Behavior
Enabled	Animation loops continuously (default)
Disabled	Animation plays once and stops on last frame

Output Structure

Generated Go Package

package asciimotion
 
import (
    "fmt"
    "strings"
    "time"
 
    tea "github.com/charmbracelet/bubbletea"
    "github.com/charmbracelet/lipgloss"
)
 
// Color themes - edit to customize for each background type
var COLORS_DARK = map[string]lipgloss.Color{
    "c0": lipgloss.Color("#9f29ff"),
    "c1": lipgloss.Color("#04c7ff"),
    // ... more colors
}
 
var COLORS_LIGHT = map[string]lipgloss.Color{
    "c0": lipgloss.Color("#7f21cc"),
    "c1": lipgloss.Color("#03a0cc"),
    // ... adjusted for light backgrounds
}
 
// Frame data structure
type Frame struct {
    Duration time.Duration
    Content  []string
    FgColors map[string]string // Maps "x,y" -> color key
    BgColors map[string]string
}
 
// Model implements tea.Model
type Model struct {
    frames            []Frame
    frameIndex        int
    isPlaying         bool
    loop              bool
    width             int
    height            int
    hasDarkBackground bool
}
 
// New creates a new animation model
func New(hasDarkBackground bool) Model {
    return Model{
        frames:            frames,
        frameIndex:        0,
        isPlaying:         true, // or false based on playback style
        loop:              true,
        width:             60,
        height:            20,
        hasDarkBackground: hasDarkBackground,
    }
}
 
// NewWithDefaults creates model with dark background (default)
func NewWithDefaults() Model {
    return New(true)
}
 
// Init, Update, View methods...

Usage Instructions

After exporting, integrate the package into your Go project:

Download the exported .go file

Create a package directory in your project

Place the file in that directory

Import and use in your Bubbletea app

Project Structure

text

myproject/
├── main.go
├── go.mod
└── animations/
    └── asciimotion/
        └── ascii_motion_anim.go

Basic Usage (Standalone)

package main
 
import (
    "fmt"
    "os"
 
    tea "github.com/charmbracelet/bubbletea"
    anim "myproject/animations/asciimotion"
)
 
func main() {
    // Create model with dark terminal background
    model := anim.New(true)
 
    // Run the program
    p := tea.NewProgram(model, tea.WithAltScreen())
    if _, err := p.Run(); err != nil {
        fmt.Printf("Error: %v\n", err)
        os.Exit(1)
    }
}

With Light Terminal Background

// For light terminal themes
model := anim.New(false)

Convenience Function

// Uses dark background by default
model := anim.NewWithDefaults()

Playback Styles

Autoplay Mode

Animation starts automatically with no user controls:

// Animation runs immediately when the program starts
model := anim.New(true)
p := tea.NewProgram(model)
p.Run()

Best for: Splash screens, loading animations, demos.

Keyboard Mode

User controls playback with keyboard shortcuts:

Key	Action
`Space`	Play/Pause toggle
`R`	Restart animation
`Q`	Quit (sends `tea.Quit`)
`←` / `H`	Previous frame (when paused)
`→` / `L`	Next frame (when paused)

// Animation responds to keyboard input
model := anim.New(true)
p := tea.NewProgram(model)
p.Run()

Best for: Interactive demos, debugging animations, presentations.

API Mode

Programmatic control via model methods for embedding in larger applications:

package main
 
import (
    tea "github.com/charmbracelet/bubbletea"
    anim "myproject/animations/asciimotion"
)
 
type AppModel struct {
    animation anim.Model
    // ... other app state
}
 
func (m AppModel) Init() tea.Cmd {
    return m.animation.Init()
}
 
func (m AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    var cmd tea.Cmd
    m.animation, cmd = m.animation.Update(msg)
    return m, cmd
}
 
func (m AppModel) View() string {
    return m.animation.View()
}

API Methods

Method	Returns	Description
`Play()`	`tea.Cmd`	Start or resume playback
`Pause()`	-	Pause playback
`Restart()`	`tea.Cmd`	Reset to frame 0 and play
`SetFrame(n)`	-	Jump to specific frame
`IsPlaying()`	`bool`	Check if currently playing
`CurrentFrame()`	`int`	Get current frame index
`TotalFrames()`	`int`	Get total number of frames
`Width()`	`int`	Get animation width
`Height()`	`int`	Get animation height

Color Modes Explained

Hex Mode

Generates exact hex color values using Lipgloss:

var COLORS_DARK = map[string]lipgloss.Color{
    "c0": lipgloss.Color("#9f29ff"),
    "c1": lipgloss.Color("#04c7ff"),
}
 
var COLORS_LIGHT = map[string]lipgloss.Color{
    "c0": lipgloss.Color("#7f21cc"),
    "c1": lipgloss.Color("#03a0cc"),
}

Best for: Terminals with true color support (iTerm2, Windows Terminal, Kitty, Alacritty).

Semantic Mode

Maps colors to ANSI 16 color palette:

var THEME_DARK = map[string]lipgloss.Color{
    "c0": lipgloss.Color("13"), // bright magenta
    "c1": lipgloss.Color("14"), // bright cyan
}
 
var THEME_LIGHT = map[string]lipgloss.Color{
    "c0": lipgloss.Color("5"),  // magenta
    "c1": lipgloss.Color("6"),  // cyan
}

Best for: Maximum compatibility, respects user's terminal color scheme.

Runtime Theme Selection

The hasDarkBackground parameter controls which color palette is used:

// The model's getColor helper selects the right palette
func (m Model) getColor(colorKey string) lipgloss.TerminalColor {
    if m.hasDarkBackground {
        return COLORS_DARK[colorKey]
    }
    return COLORS_LIGHT[colorKey]
}

Customize the color dictionaries in the exported file to fine-tune colors for each theme.

Comparing Terminal UI Exports

Feature	Bubbletea	Ink	OpenTUI
Language	Go	TypeScript	TypeScript
Framework	Bubbletea	Ink (React)	OpenTUI (React)
Architecture	MVU (Elm)	React	React
Styling	Lipgloss	Ink Text	OpenTUI Text
Playback styles	3 (auto/key/api)	API only	API only

Tips

Use Semantic mode for CLI tools distributed widely
Use Hex mode when exact colors are critical
Choose Autoplay for splash screens and loading indicators
Choose Keyboard for interactive demos
Choose API when embedding in larger applications
Customize color dictionaries after export to fine-tune appearance

Troubleshooting

Colors Look Wrong

Check if your terminal supports true colors (for Hex mode)
Try Semantic mode for better compatibility
Verify hasDarkBackground matches your terminal theme
Edit the generated color dictionaries to adjust

Animation Doesn't Play

Ensure you're calling the returned tea.Cmd from Init() and Update()
For API mode, make sure to call Play() to start playback
Check that isPlaying is true in the generated code

Animation is Choppy

Reduce frame count in the original animation
Simplify canvas content
Check terminal performance

Build Errors

Run go mod tidy to fetch dependencies
Ensure Go 1.18+ is installed
Check import paths match your project structure

Requirements

Go 1.18+
Bubbletea v0.24+
Lipgloss v0.9+

Dependencies

The generated code requires these Go modules:

require (
    github.com/charmbracelet/bubbletea v0.24.0
    github.com/charmbracelet/lipgloss v0.9.0
)

Run go mod tidy after adding the exported file to automatically fetch dependencies.