cli-loaders

A collection of cli loaders for your command-line applications.

Visit the website to see all loaders, copy keyframes, and more!

Table of Contents

• Installation
• Usage
  • Importing Loaders
  • Initializing a Loader
  • Customizing the Speed
  • Customizing Everything
  • Stopping the Loader
• Available Loaders
• Examples
  • Oh My Zsh Example
  • Next.js Component Example
• Contributing
• License
• Special Thanks

Installation

To install the package, use npm or yarn:

npm install cli-loaders;
# or
yarn add cli-loaders;
# or
bun install cli-loaders;

Usage

Importing Loaders

Import the loader initializer:

import { initCliLoader } from 'cli-loaders';

Initializing a Loader

You can initialize any loader by its name using initCliLoader:

import { initCliLoader, dots_1 } from 'cli-loaders';

// Initialize by name
initCliLoader('dots_1');

// initCliLoader(dots_1);

Customizing the Speed

You can also customize the speed of the loader:

import { initCliLoader, dots_1 } from 'cli-loaders';

// Initialize with custom speed
initCliLoader('dots_1', 150);
// initCliLoader(dots_1, 150);

Customizing Everything

New in v2.0+, you can import the cli loader initializer, initCliLoader for full customization:

import { initCliLoader, dots_14 } from 'cli-loaders';

Then use it with your own speed and keyframe arguments:

import { initCliLoader, dots_14 } from 'cli-loaders';

initCliLoader(dots_14); // Render loader
initCliLoader(dots_14, 100); // Render loader with custom speed
initCliLoader(dots_14, 100, ["⠋","⠙","⠹","⠸","⠼","⠴","⠦","⠧","⠇","⠏"]); // Render loader with speed and keyframes customized

Or you could customize it with an object:

const myAwesomeLoader = {
    speed: 100,
    keyframes: ["..", "."]
};

initCliLoader(myAwesomeLoader);

Stopping the Loader

To stop the loader, you can use clearInterval with the interval ID returned by initCliLoader:

import { initCliLoader } from 'cli-loaders';

const intervalId = initCliLoader('dots_1');

// Stop the loader after some time
setTimeout(() => {
  clearInterval(intervalId);
}, 5000);

Available Loaders

Here are some of the available loaders you can use:

• arrows_1
• arrows_2
• bars_1
• bars_2
• circles_1
• circles_2
• dots_1
• dots_2
• emojis_1
• emojis_2
• lines_1
• lines_2
• numbers_1
• numbers_2
• squares_1
• squares_2
• symbols_1
• symbols_2
• togglers_1
• togglers_2

For a full list of available loaders, please refer to the source code or the website.

Examples

Oh My Zsh Example

function start_loader() {
    local keyframes=(YOUR_COPIED_KEYFRAMES) # Keyframes for the loader
    local speed=0.1 # Speed at which the keyframes change
    local pname=$1 # PID of the process to wait for

    while kill -0 "$pname" 2>/dev/null; do
        for frame in "${keyframes[@]}"; do
            printf "\r%s %s" "$frame"
            sleep $speed
        done
    done

    # Clear the loader after the process completes
    printf "\r%s\n" "Done!"
}

function custom_loader() {
    # Example of using the loader with a background task
    (sleep 5) &  # Simulate a long-running task in the background
    start_loader $! # Call the loader with the PID of the background process
}

Nextjs Component Example

// @/components/Loader.tsx
"use client";

import React, { useEffect, useState } from 'react';

type LoaderProps = {
    speed: number;
    keyframes: string[];
    className?: string;
};

export const Loader: React.FC<LoaderProps> = ({ speed, keyframes, className }) => {
    const [currentFrame, setCurrentFrame] = useState(keyframes[0]);

    useEffect(() => {
        let index = 0;
        const interval = setInterval(() => {
            setCurrentFrame(keyframes[index]);
            index = (index + 1) % keyframes.length;
        }, speed);

        return () => clearInterval(interval);
    }, [keyframes, speed]);

    return (
        <div className={className}>{currentFrame}</div>
    );
};

Then import and use the component:

import { Loader } from "@/components/Loader";
import { dots_14 } from "cli-loaders";

const Page = () => (
    <Loader
        speed={dots_14.speed}
        keyframes={dots_14.keyframes}
        className="relative text-4xl font-mono flex flex-col justify-center items-center overflow-hidden"
    />
);

export default Page;

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License.

Special Thanks

Special thanks to cli-spinners and sindresorhus for the json file for some of the loaders in this project.