spinner

README

Spinner

Animated single-glyph progress indicator with an optional label.

Install

glyph add spinner

This copies spinner.go (and its test file) into your repo at the path your glyph.json aliases declare. After install, the file is yours: edit it, refactor it, rename it. There is no spinner library to keep in sync.

Hello, world

package main

import (
	"fmt"

	"github.com/truffle-dev/glyph/components/spinner"
	"github.com/truffle-dev/glyph/components/theme"
)

func main() {
	s := spinner.New(theme.Default).
		WithStyle(spinner.StyleDots).
		WithLabel("Working")
	fmt.Println(s.View())
}

API surface

Package: spinner

Types

• Style
• TickMsg
• Spinner

Functions and methods

• New
• WithStyle
• WithLabel
• WithInterval
• WithColor
• WithID
• Init
• Update
• View
• Frame

Dependencies

• glyph component theme (installed automatically)
• github.com/charmbracelet/bubbletea@v1.3.10
• github.com/charmbracelet/lipgloss@v1.1.0

Notes

Call Init to start the tick. Forward TickMsg through your model's Update so it reaches the spinner's Update. Use WithID when composing more than one spinner so each gets its own tick stream.

See also

• examples/showcase — single-binary TUI composing the seven main surfaces
• components/spinner/story — runnable story binary (go run -tags glyph_story ./components/spinner/story/)
• registry manifest — the JSON contract glyph add reads

License

MIT, same as the rest of glyph.

Documentation

Overview

Package spinner renders a small animated glyph next to an optional label, the way an agent UI signals "working on it". A spinner cycles through a fixed list of frames on a fixed interval and stops when the parent model removes it from the View.

Spinners are stateless from the caller's perspective: each Update returns a new Spinner with the next frame, and Init returns the first tick command that drives the animation forward.

Index

• type Spinner
  • func New(t theme.Theme) Spinner
  • func (s Spinner) Frame() int
  • func (s Spinner) Init() tea.Cmd
  • func (s Spinner) Update(msg tea.Msg) (Spinner, tea.Cmd)
  • func (s Spinner) View() string
  • func (s Spinner) WithColor(c lipgloss.Color) Spinner
  • func (s Spinner) WithID(id string) Spinner
  • func (s Spinner) WithInterval(d time.Duration) Spinner
  • func (s Spinner) WithLabel(label string) Spinner
  • func (s Spinner) WithStyle(style Style) Spinner
• type Style
• type TickMsg

Types

type Spinner

type Spinner struct {
	// contains filtered or unexported fields
}

Spinner is an animated indicator with an optional label.

func New

func New(t theme.Theme) Spinner

New constructs a Spinner using StyleDots and the theme's Primary color.

func (Spinner) Frame

func (s Spinner) Frame() int

Frame returns the current frame index.

func (Spinner) Init

func (s Spinner) Init() tea.Cmd

Init returns the first tick command. Subsequent ticks are scheduled by Update as long as the parent forwards TickMsg.

func (Spinner) Update

func (s Spinner) Update(msg tea.Msg) (Spinner, tea.Cmd)

Update advances the frame when it receives this Spinner's TickMsg. All other messages pass through unchanged.

func (Spinner) View

func (s Spinner) View() string

View renders the current frame and optional label.

func (Spinner) WithColor

func (s Spinner) WithColor(c lipgloss.Color) Spinner

WithColor overrides the foreground color of the glyph.

func (Spinner) WithID

func (s Spinner) WithID(id string) Spinner

WithID tags this spinner so a parent model with multiple spinners can route TickMsg messages by ID.

func (Spinner) WithInterval

func (s Spinner) WithInterval(d time.Duration) Spinner

WithInterval overrides the per-frame interval. Minimum 16ms.

func (Spinner) WithLabel

func (s Spinner) WithLabel(label string) Spinner

WithLabel sets text rendered after the spinner glyph. Pass "" to clear.

func (Spinner) WithStyle

func (s Spinner) WithStyle(style Style) Spinner

WithStyle picks one of the built-in frame sets and resets the interval to that style's default cadence.

type Style

type Style int

Style enumerates the built-in animation styles.

const (
	// StyleDots is a ten-frame braille rotator. The shadcn-ish default.
	StyleDots Style = iota
	// StyleLine is the classic - \ | / line spinner.
	StyleLine
	// StyleArc cycles a quarter-arc around a center point.
	StyleArc
	// StylePulse fades through four block characters.
	StylePulse
	// StyleBounce moves a single dot up and down.
	StyleBounce
)

type TickMsg

type TickMsg struct {
	ID   string
	Time time.Time
}

TickMsg is the per-frame advance message. Each Spinner produces its own TickMsg via Init and Update; parent models that compose multiple spinners can differentiate by checking the ID field.