yacspin

Unlike many other spinner libraries, yacspin decouples the animation rendering from the message updates. This provides several key benefits:

• Live Updates: You can update the spinner's Message() immediately without waiting for the next animation frame. This allows for high-frequency data updates (like progress percentages or filenames) while maintaining a slow, aesthetically pleasing animation speed.
• Dynamic Width: The library calculates the maximum width of the animation frames and adds padding. This prevents the text following the spinner from jumping left and right as the animation frames change width.
• Concurrency Safety: The spinner is safe for concurrent use. You can call methods to update settings (like Message()) while the spinner is actively animating.
• Task Representation: The spinner is designed to represent tasks. You can use Stop() to indicate a successful task completion or StopFail() to indicate a failure, with customizable characters and colors for both states.

You create a new spinner using yacspin.New(cfg), where cfg is a yacspin.Config struct.

Key configuration fields include:

• Frequency: The duration between animation frames (e.g., 100 * time.Millisecond).
• CharSet: The animation character set, typically selected from the yacspin.CharSets slice.
• Suffix: Text to appear after the spinner.
• SuffixAutoColon: If true, automatically adds a colon after the spinner/suffix.
• Message: The main text displayed.
• StopCharacter: The character used when Stop() is called (e.g., "✓").
• StopColors: A slice of color names (from yacspin.ValidColors) to use upon success.
• SpinnerAtEnd: If true, renders the spinner at the end of the line instead of the beginning.
• TerminalMode: Controls how the spinner behaves in non-interactive environments.

cfg := yacspin.Config{
	Frequency:       100 * time.Millisecond,
	CharSet:         yacspin.CharSets[59],
	Suffix:          " backing up database to S3",
	SuffixAutoColon: true,
	Message:         "exporting data",
	StopCharacter:   "✓",
	StopColors:      []string{"fgGreen"},
}

spinner, err := yacspin.New(cfg)

To use yacspin, create a new Spinner instance using yacspin.New(cfg) with a Config struct. Once created, call Start() to begin the animation. You can update the message or suffix while it is running. Finally, call Stop() to end the animation gracefully or StopFail() to indicate a failure.

Note: If you do not set ShowCursor: true in your config, the spinner will hide the terminal cursor. Ensure you call Stop() or StopFail() to restore it, otherwise you may need to manually reset your terminal.

cfg := yacspin.Config{
	Frequency:     100 * time.Millisecond,
	CharSet:       yacspin.CharSets[59],
	Suffix:        " backing up database to S3",
	Message:       "exporting data",
	StopCharacter: "✓",
	StopColors:    []string{"fgGreen"},
}

spinner, err := yacspin.New(cfg)
if err != nil {
	// handle error
}

spinner.Start()

// doing some work
time.Sleep(2 * time.Second)

spinner.Message("uploading data")

// upload...
time.Sleep(2 * time.Second)

spinner.Stop()

The yacspin.Config struct allows you to define the initial behavior of the spinner. Some fields are immutable after construction.

Immutable Fields (Set only via New())

• Frequency: time.Duration specifying animation speed.
• Writer: io.Writer for output (defaults to os.Stdout).
• ShowCursor: bool whether to show the cursor during animation.
• SpinnerAtEnd: bool if true, renders animation at the end of the line.
• ColorAll: bool if true, colors the entire line; if false, only colors the spinner character.
• TerminalMode: yacspin.TerminalMode bitflag to override TTY detection.

Mutable Fields (Can be updated after New())

• Message: The text displayed after the spinner.
• Prefix: Text printed before the spinner.
• Suffix: Text printed after the spinner.
• CharSet: The slice of strings used for animation frames.
• Colors: Colors for the spinner line (uses github.com/fatih/color syntax).
• Frequency: Update the animation speed dynamically.