loaders.zig

A fast, high-performance terminal loading indicator and progress bar library for Zig.

Documentation | API Reference | Quick Start | Source

loaders.zig is a production-oriented Zig library for animated spinners, progress bars, and multi-progress terminal UIs. It is designed for low overhead, clean output, and cross-platform terminal behavior on Linux, Windows, and macOS.

[!NOTE] This project is still evolving, but the current API is built to be practical for real CLI tools and long-running terminal workflows.

⭐ If you find loaders.zig useful, consider starring the repository.

Installation

Option A — Stable Release (Recommended for Production)

Pin to a specific tagged release for reproducible builds:

zig fetch --save https://github.com/muhammad-fiaz/loaders.zig/archive/refs/tags/0.0.1.tar.gz

This automatically adds the dependency to your build.zig.zon:

.dependencies = .{
    .loaders = .{
        .url = "https://github.com/muhammad-fiaz/loaders.zig/archive/refs/tags/0.0.1.tar.gz",
        .hash = "...", // auto-filled by zig fetch --save
    },
},

Option B — Nightly / Beta (Latest Main Branch)

Use the latest unreleased code from main. This tracks HEAD and may include breaking changes:

zig fetch --save git+https://github.com/muhammad-fiaz/loaders.zig.git

This adds a git dependency to your build.zig.zon:

.dependencies = .{
    .loaders = .{
        .url = "git+https://github.com/muhammad-fiaz/loaders.zig.git",
        .hash = "...", // auto-filled by zig fetch --save
    },
},

[!TIP] Use zig fetch --save (with URL) for the automatic flow. It resolves the hash and writes it into build.zig.zon for you.

Option C — Build from Source

git clone https://github.com/muhammad-fiaz/loaders.zig.git
cd loaders.zig
zig build

Quick Start

Progress Bar

const std = @import("std");
const loaders = @import("loaders");

pub fn main(init: std.process.Init) !void {
    const io = init.io;
    var bar = loaders.Bar.init(io, .{
        .label = "Processing",
        .total = 100,
        .show_percent = true,
        .show_elapsed = true,
    });
    defer bar.done();

    for (0..100) |i| {
        bar.setCompleted(i + 1);
        bar.render();
        try io.sleep(std.Io.Duration.fromMilliseconds(30), .awake);
    }
}

Spinner

const std = @import("std");
const loaders = @import("loaders");

pub fn main(init: std.process.Init) !void {
    const io = init.io;
    const sp = try loaders.Spinner.start(io, .{
        .text = "Syncing local database...",
        .style = loaders.SpinnerStyle.dots,
    });

    try io.sleep(std.Io.Duration.fromSeconds(2), .awake);
    sp.succeed(io, "Database synchronized successfully!");
}

Multi Progress

const std = @import("std");
const loaders = @import("loaders");

pub fn main(init: std.process.Init) !void {
    const io = init.io;
    var mb = loaders.MultiBar.init(io, std.Io.File.stderr(), null, .{});

    const a = mb.addBar(.{ .label = "Asset A", .total = 100 });
    const b = mb.addBar(.{ .label = "Asset B", .total = 100 });

    for (0..100) |i| {
        a.setCompleted(i + 1);
        b.setCompleted(i + 1);
        mb.render();
        try io.sleep(std.Io.Duration.fromMilliseconds(20), .awake);
    }

    mb.done();
}

Usage Examples

• Getting Started
• Progress Bars
• Spinners
• Multi Progress
• Styling
• Colors
• Themes
• Advanced

Configuration

The core options are available through BarOptions and SpinnerOptions in the API reference.

• label, text, and prefix for user-facing messages
• total, show_percent, show_elapsed, show_eta, and show_rate for progress details
• style, color_enabled, and custom bracket/fill fields for output control
• file and term for stream selection and terminal capability detection

See the full API at API Reference.

Documentation

Online Documentation

Full documentation is available at: https://muhammad-fiaz.github.io/loaders.zig/

Generating Local Documentation

cd docs
bun install
bun run build

The output is written to docs/.vitepress/dist/.

Building

zig build test
zig build examples
zig fmt --check build.zig src/ examples/

Contributing

Contributions are welcome! Please read the Contributing Guide for details on how to get started, run tests, and submit pull requests.

License

MIT License - see LICENSE for details.

Links

• Documentation: https://muhammad-fiaz.github.io/loaders.zig/
• API Reference: https://muhammad-fiaz.github.io/loaders.zig/api/
• Guide: https://muhammad-fiaz.github.io/loaders.zig/guide/
• Repository: https://github.com/muhammad-fiaz/loaders.zig
• Issues: https://github.com/muhammad-fiaz/loaders.zig/issues