Home

Awesome

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.

Example

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.

https://dynamic-badge-formatter-ynrxn78r2oye.runkit.sh/json?query=$.stars&url=https://api.github-star-counter.workers.dev/user/DenverCoder1&formatter=metric&label=stars&color=green&logo=github

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

https://img.shields.io/endpoint?url=https%3A%2F%2Fdynamic-badge-formatter-ynrxn78r2oye.runkit.sh%2Fjson%3Fquery%3D%24.stars%26url%3Dhttps%3A%2F%2Fapi.github-star-counter.workers.dev%2Fuser%2FDenverCoder1%26formatter%3Dmetric%26label%3Dstars%26color%3Dgreen%26logo%3Dgithub

Result:

preview

⚡ Formatters

The following values are supported for the formatter parameter:

FormatterDescriptionExample
metricFormats a number as a short metric (eg. 3.4k, 12.3M)before<br/>after
starRatingFormats a number as stars (eg. ★★★★½)before<br/>after
ordinalNumberFormats a number with an ordinal suffix (eg. 9ᵗʰ)before<br/>after
omitvRemoves a v as a prefix from a version number (eg. v1.2.3 becomes 1.2.3)before<br/>after
addvAdds a v as a prefix from a version number (eg. 1.2.3 becomes v1.2.3)before<br/>after
formatDateFormats dates as a month and year, "today" or "yesterday" can appear for recent datesbefore<br/>after
formatRelativeDateFormats a UNIX Timestamp in seconds as a relative time (eg. 3 days ago)before<br/>after

⚙️ Other Parameters

ParameterTypeDescription
urlstringrequired The JSON, XML, or YAML data URL to fetch a message value from
querystringrequired The JSONPath or XPath query for extracting a field for the value
labelstringoptional The label to use for the badge, default: "custom badge"
colorstringoptional The color to use for the badge, default: "blue"
labelColorstringoptional The color to use for the label, default: "grey"
isErrorbooleanoptional If true, the badge color is overriden to be red, default: false
logostringoptional A named logo to use from Simple Icons or base64 encoded SVG, default: none
namedLogostringoptional The name of a logo to use from Simple Icons, overrides logo, default: none
logoSvgstringoptional The base64 encoded SVG content of a logo to use, overrides logo, default: none
logoColorstringoptional The color to use for the logo, default: none
logoWidthnumberoptional The width of the logo, default: none
logoPositionnumberoptional The position offset of the logo, default: none
stylestringoptional The badge style (plastic, flat, flat-square, for-the-badge, or social), default: "flat"
cacheSecondsnumberoptional The number of seconds to cache the response, default: 300
prefixstringoptional A prefix to use before the message, default: none
suffixstringoptional A suffix to use after the message, default: none
formatterstringoptional 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

<details> <summary>Deploy to Runkit</summary>
  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
</details>

💬 Questions?

Feel free to open an issue.

❤️ Thanks

📚 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!

<p align="left"> <a href="https://www.youtube.com/channel/UCipSxT7a3rn81vGLw9lqRkg?sub_confirmation=1"><img alt="Youtube" title="Youtube" src="https://custom-icon-badges.herokuapp.com/badge/-Subscribe-red?style=for-the-badge&logo=video&logoColor=white"/></a> <a href="https://github.com/sponsors/DenverCoder1"><img alt="Sponsor with Github" title="Sponsor with Github" src="https://custom-icon-badges.herokuapp.com/badge/-Sponsor-ea4aaa?style=for-the-badge&logo=heart&logoColor=white"/></a> </p>

☕ Buy me a coffee