Skip to content
Projects

dominicegginton/spinner has 54 GitHub stars and 6 forks. GitHot measured 0 stars in 24 hours and 0 in 7 days. Last checked 2026-11-15 17:22 UTC. Last push 2026-11-01.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
0
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Powerful Swift CLI Spinners

Developer Tools

README.md

Original

Spinner

carbon (3)

  • Over 80 built-in spinner patterns
  • Create custom spinners patterns
  • Customise the spinners format
  • Handy built-in completion functions (success, error, warning, info)
  • Time your spinner and display its duration
  • Apply colors with the use of rainbow
  • Use a custom SpinnerStream for output

Install

Install via the Swift Package Manger by declaring Spinner as a dependency in your projects Package.swift:

.package(url: "https://github.com/dominicegginton/Spinner", from: "1.0.0")

Getting Started

import Foundation
import Spinner

let spinner = Spinner(.dots, "foo bar baz")
spinner.start()
sleep(2) // do work
spinner.stop()

Documentation

Creating a spinner

Create a spinner by initializing an instance of the Spinner class.

let spinner = Spinner(.dots, "foo bar baz")

The Spinner() class ins accepts optional arguments that customise the spinner.

/**
Initialize spinner
- Parameter pattern: spinner pattern
- Parameter message: message to render
- Parameter color: spinner pattern color
- Parameter speed: speed of spinner animation
- Parameter format: spinner format
- Parameter stream: output steam for spinner
- Parameter signal: signal trap implementation for spinner
*/
public init(_ pattern: SpinnerPattern, _ message: String = "", color: Color = .default, speed: Double? = nil, format: String = "{S} {T}", stream: SpinnerStream? = nil, signal: SpinnerSignal? = nil)

Start the spinner

Call the Spinner.start() function to start the spinner animation. This will also call the SpinnerStream.hideCursor() function to hide the cursor.

let spinner = Spinner(.dots, "foo bar baz")
spinner.start()

Stop the spinner

Call the Spinner.stop() function to stop the spinner animation. This will also call the SpinnerStream.showCursor() function to show the cursor.

let spinner = Spinner(.dots, "foo bar baz")
spinner.stop()

The Spinner.stop() function accepts optional arguments that customise its behaviour.

/**
Stop the spinner
- Parameter frame: final frame to render before stopping
- Parameter message: final message to render before stopping
- Parameter color: final frame color
- Parameter terminator: the string to print after all items have been printed
*/
public func stop(frame: String? = nil, message: String? = nil, color: Color? = nil, terminator: String = "\n")

Clear the spinner

The Spinner.clear() function is a helper function that stops and clears the spinner. Its implementation uses Spinner.stop() under the hood.

let spinner = Spinner(.dots, "foo bar baz")
spinner.clear()

Helper functions

Helper functions that implement Spinner.stop() under the hood are provided for common tasks.

/**
Stop and clear the spinner
*/
public func clear()

/**
Stop and render a green tick for the final pattern frame
- Parameter message: spinner message to render
*/
public func success(_ message: String? = nil)

/**
Stop and render a red cross for the final pattern frame
- Parameter message: spinner message to render
*/
public func error(_ message: String? = nil)

/**
Stop and render a yellow warning symbol for the final pattern frame
- Parameter message: spinner message to render
*/
public func warning(_ message: String? = nil)

/**
Stop and render a blue information sign  for the final pattern frame
- Parameter message: spinner message to render
*/
public func info(_ message: String? = nil)

Updating the spinner while animating

Functions are provided to update the spinner while animating.

/**
Update spinner pattern
- Parameter pattern: spinner pattern
*/
public func pattern(_ pattern: SpinnerPattern)

/**
Update spinner message
- Parameter message: message to render
*/
public func message(_ message: String)

/**
Update spinner animation speed
- Parameter speed: speed of spinner animation
*/
public func speed(_ speed: Double)

/**
Update spinner pattern color
- Parameter color: spinner pattern color
*/
public func color(_ color: Color)

/**
Update spinner format
- Parameter format: spinner format
*/
public func format(_ format: String)

Spinner patterns

Customise the spinner render format

To the spinner the Spinner.format string is taken as a base and occurrences of keys are replaced to generate the rendered spinner.

  • {S} renders the animated pattern
  • {T} renders the message
  • {D} renders the duration of since starting the spinner
let spinner = Spinner(.dots, "foo bar baz", format : "{T} - {S}") // foo bar baz - ⠧

Timing the spinners duration

Use a custom Spinner.format string that includes {D} in order to render the duration of time since starting the spinner animation

let spinner = Spinner(.dots, "foo bar baz", format: "{D} {T} - {S}") // 8s ⠧ foo bar baz

Creating Custom Patterns

The SpinnerPattern() enum initializer to create a spinner pattern with an array of strings.

let pattern = SpinnerPattern(frames: ["1","2","3","4","5"])
let spinner = Spinner(pattern, "foo bar baz", speed: 0.3) // 1 foo bar baz

CustomStreams

Spinner wraps output logic in a SpinnerStream protocol. This library provides the StdOutSpinnerStream class that implements to writing to STDOUT.

struct SwiftCLISpinnerStream: SpinnerStream {
    private let _stdout: WritableStream

    init(stdout: WritableStream) {
        _stdout = stdout
    }

    func write(string: String, terminator: String) {
        _stdout.write(string, terminator: terminator)
    }

    func hideCursor() {
        _stdout.write("\u{001B}[?25l", terminator: "")
    }

    func showCursor() {
        _stdout.write("\u{001B}[?25h", terminator: "")
    }
}

let spinner = Spinner(.dots, "foo bar baz", stream: SwiftCLISpinnerStream(stdout: stdout))

Caveat

In order to handle process interrupts (for example, SIGINT through ctrl+c) a signal handler is used to show the user's cursor before exiting. This library provides a SpinnerSignal protocol and a DefaultSpinnerSignal structure that handles this functionality by default. If this conflicts with other signals in use, a custom implementation of SpinnerSignal can be provided. See IBM-Swift/BlueSignals for a clean and safe way of handling signals. The appropriate signal handler for your project could look something like:

struct CustomSpinnerSignal: SpinnerSignal {
    func trap() {
        Signals.trap(signal: .int) { _ in
            // print("\u{001B}[?25h", terminator: "")
            // exit(0)
        }
    }
}

let spinner = Spinner(.dots, "foo bar baz", signal: CustomSpinnerSignal())