shields.rs

A high-performance badge rendering engine written in Rust, supporting SVG output and font parsing. This project is designed for developers and services that require fast, customizable, and reliable badge generation.

🟢 Bitwise-Identical SVG Output

Not only do we pursue pixel-level similarity, but we also guarantee that the generated SVG string is bitwise-identical to the output returned by shields.io for the same parameters. This ensures absolute compatibility and consistency for all use cases.

⚡️ Fast & Efficient

Over 10x faster than the Node.js badge-maker library, this Rust implementation is optimized for speed and efficiency. It can generate badges in microseconds, making it suitable for high-performance applications and services.

🎨 Supported All Styles & Logos

We support all major badge styles: flat, flat-square, plastic, social and for-the-badge. Each style can be customized with various properties such as label, message, color, logo, and more. You can easily use Simple Icons slugs to set logos for your badges, and we also support custom logos with SVG strings.

Benchmark: Rust vs Node.js badge-maker

The benchmark renders badges with a Simple Icons logo and links (cargo bench). Simple text-only badges render in well under 1 µs, and rendering is lock-free, so throughput scales with cores.

Installation

cargo add shields

Usage Example

The library provides a chainable API for customizing badges. You can set the label, message, color, and other properties using method chaining:

use shields::BadgeStyle;
use shields::builder::Badge;

fn main() {
    // Simple flat badge
    let badge = Badge::style(BadgeStyle::Flat)
        .label("test")
        .message("passing")
        .build();
    println!("{badge}");

    // Plastic badge with custom colors
    let badge = Badge::style(BadgeStyle::Plastic)
        .label("version")
        .message("1.0.0")
        .label_color("#555")
        .message_color("#4c1")
        .build();
    println!("{badge}");

    // Social badge with logo and links
    let badge = Badge::style(BadgeStyle::Social)
        .label("github")
        .message("stars")
        .logo("github")
        .link("https://github.com/user/repo")
        .extra_link("https://github.com/user/repo/stargazers")
        .build();
    println!("{badge}");
}

Additional options beyond the shields.io URL parameters:

use shields::builder::Badge;

let svg = Badge::flat()
    .label("build")
    .message("passing")
    // Unique id suffix, required when several badges are inlined in one HTML
    // page (inline SVGs share the page's id namespace).
    .id_suffix("badge1")
    // Widen the logo box (default 14px) for wide logos.
    .logo_width(20)
    .build();

If you only render text badges or custom SVG logos, disable the embedded Simple Icons set to cut compile time and binary size:

shields = { version = "1", default-features = false }

See examples/server.rs for a dependency-free HTTP badge service using the serde-friendly BadgeParamsOwned type.

There is also a plain parameter-struct API if you prefer explicit construction:

use shields::{BadgeParams, BadgeStyle, render_badge_svg};

let svg = render_badge_svg(&BadgeParams {
    style: BadgeStyle::Flat,
    label: Some("build"),
    message: Some("passing"),
    label_color: None,
    message_color: Some("brightgreen"),
    link: None,
    extra_link: None,
    logo: None,
    logo_color: None,
});

License

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

Community & Contact

• GitHub: https://github.com/Jannchie/shields.rs
• Documentation: https://docs.rs/shields
• Author: Jannchie (jannchie@gmail.com)