Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kei-k23/spinix

Spinix ๐ŸŒ€ is a Go package that provides terminal-based highly customizable and performance loading animations, including spinners and progress bars.
https://github.com/kei-k23/spinix

cli go lib library progress-bar spinner terminal

Last synced: 19 days ago
JSON representation

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

Awesome Lists containing this project

README 

        
# Spinix



[![Go Test](https://github.com/Kei-K23/spinix/actions/workflows/test.yml/badge.svg)](https://github.com/Kei-K23/spinix/actions/workflows/test.yml)



**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`:



```bash

go get github.com/Kei-K23/spinix

```



## Usage



### Spinners



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



```go

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:



```go

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:



```go

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:



```go

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



```go

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



```go

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:



```go

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](./images/green.gif)



## 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](LICENSE) file for more details.



## Contributors



Thanks to all the amazing contributors for making **spinix** better!