badgelib

badgelib is a Rust library for rendering customizable SVG badges directly in your application. Use it when you want to generate badges without running a separate badge service. It powers badges.ws; the web service and its data integrations live in the main badges repository.

Install

cargo add badgelib

Quick start

use badgelib::{Badge, Color};

fn main() -> std::io::Result<()> {
  let svg = Badge::new()
    .label("build")
    .value("passing")
    .value_color(Color::Green)
    .logo("rust")
    .radius(4)
    .to_svg();

  std::fs::write("badge.svg", svg)
}

Badge::to_svg() returns the complete SVG document as a String. Badges can include separate label and value colors, left-to-right gradients, an icon from Simple Icons, a custom icon color, and a border radius.

Gradients

Pass two or more colors to distribute them evenly from left to right:

use badgelib::{Badge, Color};

let svg = Badge::new()
  .label("build")
  .value("passing")
  .value_gradient([Color::Red, Color::Orange, Color::Cyan])
  .logo("rust")
  .to_svg();

Use label_gradient for the left side of a two-part badge. Calling a solid-color setter replaces the corresponding gradient, and calling a gradient setter replaces the solid color.

Custom icons

logo looks up a slug in Simple Icons, including slugs removed or renamed in historical releases. Simple Icons only supports single-color icons; for anything else, pass raw SVG markup directly with icon_svg:

use badgelib::Badge;

let svg = Badge::new()
  .value("custom icon")
  .icon_svg(r##"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
    <path d="M12 3 L14 10 L21 12 L14 14 L12 21 L10 14 L3 12 L10 10 Z" fill="#facc15" />
  </svg>"##)
  .to_svg();

Animations

Select one opinionated animation with animation. Calling it again replaces the previous selection; speed, direction, easing, and target area are intentionally not configurable. All animations respect the viewer's reduced-motion preference.

Animation::Flow scrolls every configured gradient continuously. A gradient on only the label or value animates only that section; solid-color sections remain static.

use badgelib::{Animation, Badge, Color};

let svg = Badge::new()
  .value("flowing")
  .value_gradient([Color::Red, Color::Orange, Color::Cyan])
  .animation(Animation::Flow)
  .to_svg();

Animation::Shine periodically sweeps a soft diagonal light streak across the full width of the badge, including both label and value sections.

Animation::Aurora layers one continuous field of slowly drifting, softly blurred lights across the full badge. Its palette is derived from all existing label and value background colors.

let svg = Badge::new()
  .value("northern lights")
  .value_color(Color::Blue)
  .animation(Animation::Aurora)
  .to_svg();

Built-in badge types

The library includes helpers for common badge values and their default formatting:

use badgelib::{Badge, Period};

let version = Badge::new().for_version("version", "1.2.0");
let license = Badge::new().for_license("MIT");
let downloads = Badge::new().for_downloads(Period::Month, 1_234_567);
let build = Badge::new().for_ci_status("build", true);
let size = Badge::new().for_size("size", 1_234_567);
let rating = Badge::new().for_rating("rating", 4.5, 5.0);

Available helpers cover versions, licenses, downloads, CI status, counts, sizes, ratings, star ratings, and relative durations. You can override their labels and colors with the regular builder methods.

JSON output

Use Badge::to_json() when you need the badge parameters as JSON instead of rendered SVG:

let json = badgelib::Badge::new()
  .label("version")
  .value("v1.2.0")
  .to_json();

{"label":"version","labelColor":null,"value":"v1.2.0","color":null,"logo":null,"logoColor":null,"radius":null,"style":"flat"}

format and cache also appear when the axum feature is enabled.

Axum integration

Enable the optional axum feature to return a Badge directly from a handler:

cargo add badgelib --features axum

use badgelib::Badge;

async fn version_badge() -> Badge {
  Badge::new().for_version("version", env!("CARGO_PKG_VERSION"))
}

With this feature enabled, Badge implements Axum's IntoResponse and returns SVG by default with the appropriate content type and cache headers.

Development

Clone the repository, then run the existing checks:

git clone https://github.com/vladkens/badgelib.git
cd badgelib
make check
make test

make update refreshes dependencies and regenerates the embedded historical Simple Icons map and font-width table.

Credits

• Inspired by Shields.io and Badgen.
• Icons are provided by Simple Icons.
• Badge text is rendered with DejaVu Sans.

License

Distributed under the MIT License.