Dynamic Badge Formatter

stars issues license discord

Format Shields Dynamic Badges to look consistent using formatters for metrics, versions, stars and more.

Dynamic Badge Formatter works alongside shields.io using Endpoint Badges with a Runkit Endpoint.

⚡ How to use

The easiest way to get started is to try out the demo site!

demo site

Advanced steps

  1. Choose a JSON, XML, or YAML data URL to extract data from.

  2. Create a query using a JSONPath (for JSON or YAML) or XPath (for XML) expression.

  3. Set the url and query parameters at the endpoint https://dynamic-badge-formatter-ynrxn78r2oye.runkit.sh/json, using /json for JSON, /xml for XML, and /yaml for YAML.

  4. Set additional customizations as query parameters, such as the color, label, labelColor, logo, etc., and specify a formatter to use (see below).

  5. URL Encode the new endpoint URL and append it after https://img.shields.io/endpoint?url=. You can also do this by pasting the URL at shields.io/endpoint.


The following is a JSON API I want to use for displaying data. I want to display the stars but formatted as a metric (eg. "3.2k" instead of "3227"). To extract the star count from the JSON, I will use the query $.stars.

// https://api.github-star-counter.workers.dev/user/DenverCoder1
  "stars": 3227,
  "forks": 1207

To create the Runkit URL, pass the query, url, and additional parameters to the endpoint. In this example, I set formatter to metric, label to stars, color to green, and logo to github.


Using the customizer at https://shields.io/endpoint, I can turn this endpoint into a badge.




⚡ Formatters

The following values are supported for the formatter parameter:

Formatter Description Example
metric Formats a number as a short metric (eg. 3.4k, 12.3M) beforeafter
starRating Formats a number as stars (eg. ★★★★½) beforeafter
ordinalNumber Formats a number with an ordinal suffix (eg. 9ᵗʰ) beforeafter
omitv Removes a v as a prefix from a version number (eg. v1.2.3 becomes 1.2.3) beforeafter
addv Adds a v as a prefix from a version number (eg. 1.2.3 becomes v1.2.3) beforeafter
formatDate Formats dates as a month and year, “today” or “yesterday” can appear for recent dates beforeafter
formatRelativeDate Formats a UNIX Timestamp in seconds as a relative time (eg. 3 days ago) beforeafter

⚙️ Other Parameters

Parameter Type Description
url string required The JSON, XML, or YAML data URL to fetch a message value from
query string required The JSONPath or XPath query for extracting a field for the value
label string optional The label to use for the badge, default: “custom badge”
color string optional The color to use for the badge, default: “blue”
labelColor string optional The color to use for the label, default: “grey”
isError boolean optional If true, the badge color is overriden to be red, default: false
logo string optional A named logo to use from Simple Icons or base64 encoded SVG, default: none
namedLogo string optional The name of a logo to use from Simple Icons, overrides logo, default: none
logoSvg string optional The base64 encoded SVG content of a logo to use, overrides logo, default: none
logoColor string optional The color to use for the logo, default: none
logoWidth number optional The width of the logo, default: none
logoPosition number optional The position offset of the logo, default: none
style string optional The badge style (plastic, flat, flat-square, for-the-badge, or social), default: “flat”
cacheSeconds number optional The number of seconds to cache the response, default: 300
prefix string optional A prefix to use before the message, default: none
suffix string optional A suffix to use after the message, default: none
formatter string optional The name of a formatter to use on the message (see options above), default: none

🤗 Contributing

We welcome contributions!

Please see CONTRIBUTING.md for details.

📤 Deploying it on your own

Deploy to Runkit
  1. Sign in to Runkit or create a new account at https://runkit.com
  2. Create a new notebook
  3. Paste the contents of index.js into the notebook
  4. Click endpoint to get your endpoint to run requests against

💬 Questions?

Feel free to open an issue.

❤️ Thanks

  • Shields.io for all the great work they have done with creating tools for creating Dynamic and Endpoint Badges

📚 License

This project is licensed under the MIT license.

Some formatters make use of code written for shields.io in the public domain.

🤩 Support

💙 If you like this project, give it a ⭐ and share it with friends!

Youtube Sponsor with Github

☕ Buy me a coffee


View Github