spinner

spinner is a small, dependency-light Go package that renders an animated terminal indicator while a CLI command performs background work. It ships 90 predefined character sets — arrows, braille dots, block bars, ASCII faces, and more — and accepts any []string as a custom animation frame set.

Beyond the animation itself, the library exposes prefix/suffix text, ANSI color and text-attribute styling via the fatih/color package, a pluggable io.Writer so output can target stdout, stderr, or any custom sink for piping, pre/post-update hook functions, and a final message that prints once the spinner stops. It detects whether it is attached to an interactive terminal and disables itself for CI logs or redirected output, with Windows Terminal-aware cursor handling.

What You Get

• 90 predefined character sets (arrows, braille dots, block bars, ASCII faces, and more) selectable by index, or supply your own []string
• Color and text-attribute styling (bold, italic, underline, foreground/background colors) via the fatih/color package
• Prefix/suffix text, a final completion message, and PreUpdate/PostUpdate hook functions that run on every animation frame
• A pluggable io.Writer/WriterFile so output can target stdout, stderr, or a custom sink for piping and redirection
• Automatic terminal detection that disables the spinner when output isn’t an interactive TTY, such as in CI logs

Common Use Cases

• Showing progress during long-running CLI operations like downloads, builds, or API calls
• Adding a status indicator to deployment or provisioning tools while waiting on remote operations
• Piping spinner output to stderr so stdout stays clean for programmatic consumption
• Building interactive installer or setup scripts that need visual feedback between steps

Under The Hood

Architecture The library is a single-file package (spinner.go) built around one exported Spinner struct configured via a functional-options pattern (Option func(*Spinner), with WithColor, WithSuffix, WithFinalMSG, WithHiddenCursor, WithWriter, and WithWriterFile). New() constructs the struct with sensible defaults, applies the supplied options, and Start() spawns a single goroutine that loops through the active character set, guarding all shared state with a mutex and coordinating shutdown through a buffered stopChan. Because the entire animation and state model lives in one struct with a narrow public surface, the blast radius of any change to the core loop is small and easy to reason about.

Tech Stack Written for Go 1.17+ with a minimal dependency footprint: github.com/fatih/color provides ANSI color and attribute rendering, golang.org/x/term supplies terminal-size and TTY detection, and go-colorable/go-isatty/golang.org/x/sys ride along as indirect dependencies for cross-platform terminal handling. Build and test are driven by a plain Makefile, with CircleCI running make test as the only CI step — there is no bundler, database, or web framework involved since this is a pure terminal-output library.

Code Quality spinner_test.go carries a substantial test suite — construction, start/stop/restart, enable/disable, color validation, custom writers, hook functions, character-set reversal, speed updates, and a dedicated table-driven suite for the line-wrapping/erase math, plus two benchmarks. Error handling is minimal but explicit, using a single sentinel error (errInvalidColor) rather than swallowing bad input. Naming follows idiomatic Go conventions (exported PascalCase, unexported camelCase) and every exported symbol carries a doc comment, though there’s no linter configuration or static-analysis step beyond go test in CI.

API Design The public API favors low boilerplate: spinner.New(charSet, delay) with optional functional-option arguments gets a spinner running in a couple of lines, and the CharSets slice removes any need to hand-author animation frames. Prefix/Suffix fields, Color(), UpdateCharSet(), UpdateSpeed(), and Reverse() cover the common runtime adjustments without needing to reconstruct the spinner. One minor rough edge: the Options struct is declared to describe configuration fields but isn’t actually consumed anywhere in the constructor, leaving it as documentation rather than a used type.