/spinix

Spinix ๐ŸŒ€ is a Go package that provides terminal-based highly customizable and performance loading animations, including spinners and progress bars.

Primary LanguageGoMIT LicenseMIT

Spinix

Go Test

Spinix ๐ŸŒ€ is a Go package that provides terminal-based loading animations, including spinners and progress bars. It supports customizable themes, colors, and speeds, allowing developers to create visually appealing loading indicators that can fit various terminal environments and aesthetics.

Features

  • Spinners: Multiple spinner styles with customizable speed and colors.
  • Progress Bars: A customizable progress bar with adjustable width, characters, and styles.
  • Thread Safety: Safe to use in concurrent environments with mutexes.
  • Customizable Themes: Use predefined themes or create your own custom spinner themes.

Installation

To install Spinix, use go get:

go get github.com/Kei-K23/spinix

Usage

Spinners

Hereโ€™s how to create and use a spinner:

package main

import (
	"time"
	"github.com/Kei-K23/spinix"
)

func main() {
	spinner := spinix.NewSpinner().
		SetSpinnerColor("\033[34m").
		SetMessage("Loading...").
		SetMessageColor("\033[36m").
		SetSpeed(100 * time.Millisecond) // Adjust speed if necessary

	spinner.Start()

	// Simulate some work
	time.Sleep(5 * time.Second)

	spinner.Stop()

    // spinix.NewSpinner() will also create spinner with default properties
    // e.g
    // spinner := spinix.NewSpinner()
	// spinner.Start()
	// time.Sleep(5 * time.Second)
	// spinner.Stop()
}

Progress Bars

Creating and using a progress bar is just as straightforward:

package main

import (
	"time"
	"github.com/Kei-K23/spinix"
)

func main() {
	progressBar := spinix.NewProgressBar().
		SetWidth(50).
		SetColor("\033[32m").
		SetLabel("Progress:")

	progressBar.Start()

	for i := 0; i <= 100; i++ {
		progressBar.Update(i)
		time.Sleep(50 * time.Millisecond) // Simulate work
	}

	progressBar.Stop()

    // spinix.NewProgressBar() will also create progress bar with default properties.
    // e.g
    // progressBar := spinix.NewProgressBar()
    // progressBar.Start()
	// for i := 0; i <= 100; i++ {
	// 	progressBar.Update(i)
	// 	time.Sleep(50 * time.Millisecond) // Simulate work
	// }
	// progressBar.Stop()
}

Customization

Spinners

You can customize the spinner's message, colors, speed, theme and define a custom callback function that will run once the and spinner is completed:

func main() {
	spinner := spinix.NewSpinner().
		SetMessage("Processing...").
		SetMessageColor("\033[33m").
		SetCustomTheme([]string{"โ–", "โ–ƒ", "โ–„", "โ–…", "โ–†", "โ–‡", "โ–ˆ", "โ–‡", "โ–†", "โ–…", "โ–„", "โ–ƒ"}).
		SetSpinnerColor("\033[31m"). // Red color (you can use every color you want with that format but spinner color will not work with emoji spinner)
		SetSpeed(200 * time.Millisecond).
		SetCallback(func() {
			fmt.Println("The callback function has executed!")
		})

	spinner.Start()
	time.Sleep(2 * time.Second) // Simulate a task
	spinner.Stop()
}

Progress Bars

You can customize the progress bar's message, width, color, appearance and define a custom callback function that will run once the and progress bar is completed:

func main() {
	progressBar := spinix.NewProgressBar().
		SetWidth(60).
		SetBarChar("โ–ˆ").
		SetEmptyChar("โ–‘").
		SetBorders("[", "]").
		SetShowPercentage(true).
		SetCallback(func() {
			fmt.Println("The callback function has executed!")
		})

	progressBar.Start()

	for i := 0; i <= 100; i++ {
		progressBar.Update(i)
		time.Sleep(50 * time.Millisecond) // Simulate work
	}

	progressBar.Stop()
}

Use Predefined Spinner and Progress bar

Spinners

You can also use predefined spinner themes that provided by spinix: See all available predefined spinner themes below

func main() {
	spinner := spinix.NewSpinner().
		SetMessage("Processing...").
		SetMessageColor("\033[33m").
		SetTheme(spinix.SpinnerRotatingArrow)

	spinner.Start()

	// Simulate some work
	time.Sleep(5 * time.Second)

	spinner.Stop()
}

Progress Bars

You can use predefined progress bar style that provided by spinix: See all available predefined progress bar styles below

func main() {
	progressBar := spinix.NewProgressBar().
		SetStyle(spinix.PbStyleBasic).
		SetShowPercentage(true)

	progressBar.Start()

	for i := 0; i <= 100; i++ {
		progressBar.Update(i)
		time.Sleep(50 * time.Millisecond) // Simulate work
	}

	progressBar.Stop()
}

Available Spinner Themes

The Spinix package comes with several predefined spinner themes. Hereโ€™s a list of the available styles along with their visualizations:

Spinner Theme Visualization
SpinnerClassicDots โ ‹ โ ™ โ น โ ธ โ ผ โ ด โ ฆ โ ง โ ‡ โ 
SpinnerLineTheme - \
SpinnerPulsatingDot โ  โ ‚ โ „ โ ‚
SpinnerGrowingBlock โ– โ–ƒ โ–„ โ–… โ–† โ–‡ โ–ˆ โ–‡ โ–† โ–… โ–„ โ–ƒ
SpinnerRotatingArrow โ†’ โ†˜ โ†“ โ†™ โ† โ†– โ†‘ โ†—
SpinnerArcLoader โ—œ โ—  โ— โ—ž โ—ก โ—Ÿ
SpinnerClock ๐Ÿ•› ๐Ÿ• ๐Ÿ•‘ ๐Ÿ•’ ๐Ÿ•“ ๐Ÿ•” ๐Ÿ•• ๐Ÿ•– ๐Ÿ•— ๐Ÿ•˜ ๐Ÿ•™ ๐Ÿ•š
SpinnerCircleDots โ— โ—“ โ—‘ โ—’
SpinnerBouncingBall โ  โ ‚ โ „ โ ‚
SpinnerFadingSquares โ–– โ–˜ โ– โ–—
SpinnerDotsFading โ  โ ‚ โ „ โ ‚ โ  โ ‚ โ „ โ ‚
SpinnerEarth ๐ŸŒ ๐ŸŒŽ ๐ŸŒ
SpinnerSnake โ ˆ โ  โ   โข€ โก€ โ „ โ ‚ โ 
SpinnerTriangle โ—ข โ—ฃ โ—ค โ—ฅ
SpinnerSpiral โ–– โ–˜ โ– โ–— โ–˜ โ– โ–– โ–—
SpinnerWave โ– โ–‚ โ–ƒ โ–„ โ–… โ–† โ–‡ โ–ˆ โ–‡ โ–† โ–… โ–„ โ–ƒ โ–‚ โ–
SpinnerWeather ๐ŸŒค๏ธ โ›… ๐ŸŒฅ๏ธ โ˜๏ธ ๐ŸŒง๏ธ โ›ˆ๏ธ ๐ŸŒฉ๏ธ ๐ŸŒจ๏ธ
SpinnerRunningPerson ๐Ÿƒ๐Ÿ’จ ๐Ÿƒ๐Ÿ’จ๐Ÿ’จ ๐Ÿƒ๐Ÿ’จ๐Ÿ’จ๐Ÿ’จ ๐Ÿƒโ€โ™‚๏ธ๐Ÿ’จ ๐Ÿƒโ€โ™‚๏ธ๐Ÿ’จ๐Ÿ’จ ๐Ÿƒโ€โ™€๏ธ๐Ÿ’จ ๐Ÿƒโ€โ™€๏ธ๐Ÿ’จ๐Ÿ’จ
SpinnerRunningCat ๐Ÿฑ๐Ÿ’จ ๐Ÿˆ๐Ÿ’จ ๐Ÿฑ๐Ÿ’จ๐Ÿ’จ ๐Ÿˆ๐Ÿ’จ๐Ÿ’จ
SpinnerRunningDog ๐Ÿ•๐Ÿ’จ ๐Ÿถ๐Ÿ’จ ๐Ÿ•โ€๐Ÿฆบ๐Ÿ’จ ๐Ÿ•๐Ÿ’จ๐Ÿ’จ
SpinnerCycling ๐Ÿšด ๐Ÿšดโ€โ™‚๏ธ ๐Ÿšดโ€โ™€๏ธ ๐Ÿšต ๐Ÿšตโ€โ™‚๏ธ ๐Ÿšตโ€โ™€๏ธ
SpinnerCarLoading ๐Ÿš—๐Ÿ’จ ๐Ÿš™๐Ÿ’จ ๐Ÿš“๐Ÿ’จ ๐Ÿš•๐Ÿ’จ ๐Ÿš๐Ÿ’จ ๐Ÿš”๐Ÿ’จ
SpinnerRocket ๐Ÿš€ ๐Ÿš€๐Ÿ’จ ๐Ÿš€๐Ÿ’จ๐Ÿ’จ ๐Ÿš€๐Ÿ’จ๐Ÿ’จ๐Ÿ’จ ๐Ÿš€๐ŸŒŒ ๐Ÿš€๐ŸŒ 
SpinnerOrbit ๐ŸŒ‘ ๐ŸŒ’ ๐ŸŒ“ ๐ŸŒ” ๐ŸŒ• ๐ŸŒ– ๐ŸŒ— ๐ŸŒ˜
SpinnerTrain ๐Ÿš† ๐Ÿš„ ๐Ÿš… ๐Ÿš‡ ๐ŸšŠ ๐Ÿš‰
SpinnerAirplane โœˆ๏ธ ๐Ÿ›ซ ๐Ÿ›ฌ โœˆ๏ธ๐Ÿ’จ โœˆ๏ธ๐Ÿ’จ๐Ÿ’จ
SpinnerFireworks ๐ŸŽ† ๐ŸŽ‡ ๐ŸŽ†๐ŸŽ‡ ๐ŸŽ‡๐ŸŽ†
SpinnerPizzaDelivery ๐Ÿ•๐Ÿ’จ ๐Ÿ”๐Ÿ’จ ๐ŸŒญ๐Ÿ’จ ๐ŸŸ๐Ÿ’จ
SpinnerHeartbeat ๐Ÿ’“ ๐Ÿ’— ๐Ÿ’– ๐Ÿ’˜ ๐Ÿ’ž ๐Ÿ’ ๐Ÿ’–

Available Progress Bar Styles

The ProgressBar can be styled using various predefined styles. Hereโ€™s a list of available styles:

Progress Bar Style Description
PbStyleBasic ===========================------------- 69%
PbStyleClassic [############################..] 95%
PbStyleMinimal ******* 79%
PbStyleBold โฎโ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ–  โฏ 93%
PbStyleDashed [โ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฎโ–ฏโ–ฏโ–ฏโ–ฏโ–ฏโ–ฏโ–ฏโ–ฏโ–ฏโ–ฏโ–ฏโ–ฏโ–ฏโ–ฏโ–ฏโ–ฏโ–ฏโ–ฏ] 61%
PbStyleElegant โฌโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฐโ–ฑโ–ฑโ–ฑโ–ฑโ–ฑโ–ฑโ–ฑโ–ฑโญ 79
PbStyleEmoji ๐Ÿšฉ๐Ÿš€๐Ÿš€๐Ÿš€๐Ÿš€๐Ÿš€๐Ÿš€๐Ÿš€๐Ÿš€๐Ÿš€๐Ÿš€๐Ÿš€๐Ÿš€๐Ÿš€๐Ÿš€๐Ÿš€๐Ÿš€๐Ÿš€โœจโœจโœจโœจโœจโœจโœจโœจ๐ŸŽฏ 71%
PbStyleFuturistic โŸฆโ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‰โ—‹โ—‹โ—‹โ—‹โ—‹โ—‹โ—‹โ—‹โ—‹โ—‹โ—‹โ—‹โ—‹โ—‹โ—‹โ—‹โ—‹โŸง 59%
PbStyleGreenDevelopment ๐ŸŒฑ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ๐ŸŒฟ____๐ŸŒณ 91%

Example

Hereโ€™s a complete example that demonstrates both the spinner and the progress bar together:

package main

import (
	"time"
	"github.com/Kei-K23/spinix"
)

func main() {
	spinner := spinix.NewSpinner()
	progressBar := spinix.NewProgressBar()

	spinner.SetMessage("Loading Data...")
	spinner.Start()
	progressBar.SetWidth(50)
	progressBar.SetColor("\033[36m") // Cyan
	progressBar.Start()

	for i := 0; i <= 100; i++ {
		progressBar.Update(i)
		time.Sleep(50 * time.Millisecond) // Simulate work
	}

	progressBar.Stop()
	spinner.Stop()
}

Demo

The demo run for the progress bar with style as green.

green-progress-bar

Contributing

Contributions are welcome! Please feel free to open issues, submit pull requests, or provide feedback.

License

This project is licensed under the MIT License. See the LICENSE file for more details.

Contributors

Thanks to all the amazing contributors for making spinix better!