Top Related Projects
📈 A small, fast chart for time series, lines, areas, ohlc & bars
Simple HTML5 Charts using the <canvas> tag
Bring data to life with SVG, Canvas and HTML. :bar_chart::chart_with_upwards_trend::tada:
Open-source JavaScript charting library behind Plotly and Dash
📊 Interactive JavaScript Charts built on SVG
Generation of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown
Quick Overview
Shields.io is a service for concise, consistent, and legible badges in SVG and raster format. It provides a way to add dynamic and static badges to GitHub repositories, documentation, or any web project. These badges can display various information such as build status, version numbers, and other metadata.
Pros
- Extensive collection of pre-defined badges for popular services and metrics
- Customizable badge designs and colors
- Easy integration with various platforms and services
- Supports both static and dynamic badges
Cons
- Dependency on external service for dynamic badges
- Potential performance impact if many badges are used
- Limited advanced customization options
- Occasional service downtime can affect badge visibility
Code Examples
![GitHub stars](https://img.shields.io/github/stars/badges/shields.svg?style=social&label=Stars)
This code generates a badge showing the number of GitHub stars for the shields repository.
![npm version](https://img.shields.io/npm/v/npm.svg)
This code creates a badge displaying the latest version of npm package on npmjs.com.
![Custom badge](https://img.shields.io/badge/custom-badge-blue.svg)
This code produces a custom badge with the text "custom badge" in blue color.
Getting Started
To use Shields.io badges in your project, simply add the appropriate markdown or HTML code to your README.md file or web page. Here's a quick example:
# My Awesome Project
![Build Status](https://img.shields.io/travis/username/repo.svg)
![License](https://img.shields.io/github/license/username/repo.svg)
![Version](https://img.shields.io/github/v/release/username/repo.svg)
Description of your project goes here.
Replace username
and repo
with your GitHub username and repository name. You can find more badge options and customization on the Shields.io website.
Competitor Comparisons
📈 A small, fast chart for time series, lines, areas, ohlc & bars
Pros of uPlot
- Extremely lightweight and fast charting library
- Optimized for time series data visualization
- Minimal dependencies and small bundle size
Cons of uPlot
- Limited chart types and customization options
- Steeper learning curve for complex visualizations
- Less extensive documentation compared to Shields
Code Comparison
uPlot:
let uplot = new uPlot(options, data, document.body);
Shields:
<img src="https://img.shields.io/badge/example-badge-blue" alt="Example Badge">
Summary
uPlot is a specialized charting library focused on performance and efficiency, particularly for time series data. It offers blazing-fast rendering and a small footprint, making it ideal for applications dealing with large datasets or requiring real-time updates.
Shields, on the other hand, is a service for creating and displaying badges, typically used in README files and documentation. It's not a charting library but rather a tool for visual representation of metadata, build statuses, and other project information.
While uPlot excels in creating interactive charts with minimal overhead, Shields provides a simple way to add informative badges to project pages. The choice between the two depends on the specific needs of your project: data visualization (uPlot) or status/information display (Shields).
Simple HTML5 Charts using the <canvas> tag
Pros of Chart.js
- Focused on creating interactive and customizable charts
- Extensive documentation and examples for various chart types
- Responsive and mobile-friendly design
Cons of Chart.js
- Limited to chart-related functionality
- Larger file size due to comprehensive charting features
- Steeper learning curve for complex chart configurations
Code Comparison
Chart.js example:
const ctx = document.getElementById('myChart').getContext('2d');
new Chart(ctx, {
type: 'bar',
data: {
labels: ['Red', 'Blue', 'Yellow'],
datasets: [{
label: 'Colors',
data: [12, 19, 3]
}]
}
});
Shields example:
![GitHub stars](https://img.shields.io/github/stars/username/repo)
![npm version](https://img.shields.io/npm/v/package-name)
![Build status](https://img.shields.io/travis/username/repo)
Summary
Chart.js is a powerful library for creating various types of charts, offering extensive customization options and responsive design. However, it's specifically focused on charting and may have a larger file size.
Shields, on the other hand, is designed for creating simple, static badges and doesn't provide charting capabilities. It's lightweight and easy to use for displaying metadata and status information.
The choice between these libraries depends on the specific needs of your project: Chart.js for interactive data visualization, or Shields for concise status indicators and metadata display.
Bring data to life with SVG, Canvas and HTML. :bar_chart::chart_with_upwards_trend::tada:
Pros of D3
- Powerful and flexible data visualization library
- Extensive documentation and large community support
- Wide range of chart types and customization options
Cons of D3
- Steeper learning curve for beginners
- Requires more code for simple visualizations
- Performance can be an issue with large datasets
Code Comparison
D3:
d3.select("body")
.append("svg")
.attr("width", 200)
.attr("height", 200)
.append("circle")
.attr("cx", 100)
.attr("cy", 100)
.attr("r", 50)
.style("fill", "blue");
Shields:
![Custom Badge](https://img.shields.io/badge/Hello-World-blue)
Key Differences
- Purpose: D3 is for data visualization, while Shields is for creating badges
- Complexity: D3 offers more advanced features but requires more code
- Integration: Shields is easier to integrate into README files and documentation
- Customization: D3 provides more control over visual elements
- Use cases: D3 is suited for interactive charts, while Shields is ideal for status indicators
Summary
D3 is a comprehensive data visualization library with a wide range of capabilities, but it has a steeper learning curve. Shields, on the other hand, is a simpler tool focused on creating badges for project documentation. Choose D3 for complex data visualizations and Shields for quick, informative badges in your project's README or documentation.
Open-source JavaScript charting library behind Plotly and Dash
Pros of Plotly.js
- Powerful interactive data visualization library
- Supports a wide range of chart types and customization options
- Extensive documentation and community support
Cons of Plotly.js
- Larger file size and potentially slower load times
- Steeper learning curve for complex visualizations
- May be overkill for simple projects or static graphics
Code Comparison
Plotly.js:
Plotly.newPlot('myDiv', [{
x: [1, 2, 3, 4],
y: [10, 15, 13, 17],
type: 'scatter'
}]);
Shields:
![Custom Badge](https://img.shields.io/badge/custom-badge-blue)
Key Differences
- Purpose: Plotly.js is for data visualization, while Shields is for creating status badges
- Complexity: Plotly.js offers advanced charting capabilities, Shields focuses on simple, static badges
- Use cases: Plotly.js is ideal for interactive dashboards, Shields is perfect for project documentation
- Implementation: Plotly.js requires JavaScript integration, Shields can be used with simple markdown
- Customization: Plotly.js allows for extensive chart customization, Shields offers limited badge styling options
Conclusion
Choose Plotly.js for complex, interactive data visualizations. Opt for Shields when you need simple, informative badges for project documentation or status indicators.
📊 Interactive JavaScript Charts built on SVG
Pros of ApexCharts.js
- Offers a wide range of interactive and customizable chart types
- Provides responsive and mobile-friendly charts out of the box
- Supports real-time data updates and animations
Cons of ApexCharts.js
- Larger file size and potentially higher performance overhead
- Steeper learning curve due to more complex API and configuration options
- May be overkill for simple data visualization needs
Code Comparison
ApexCharts.js:
var options = {
chart: { type: 'line' },
series: [{ data: [30, 40, 35, 50, 49, 60, 70] }],
xaxis: { categories: [1991, 1992, 1993, 1994, 1995, 1996, 1997] }
};
var chart = new ApexCharts(document.querySelector("#chart"), options);
chart.render();
Shields:
![GitHub stars](https://img.shields.io/github/stars/username/repo)
![npm version](https://img.shields.io/npm/v/package-name)
![Build Status](https://img.shields.io/travis/username/repo)
Summary
ApexCharts.js is a powerful charting library for creating interactive and visually appealing charts, while Shields is focused on generating simple, static badges for documentation and project status. ApexCharts.js offers more flexibility and features for data visualization, but Shields excels in providing quick, easy-to-use status indicators for various project metrics.
Generation of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown
Pros of Mermaid
- Generates diagrams and charts from text-based descriptions
- Supports a wide variety of diagram types (flowcharts, sequence diagrams, Gantt charts, etc.)
- Can be easily integrated into Markdown documents
Cons of Mermaid
- Steeper learning curve for complex diagrams
- Limited customization options compared to dedicated diagramming tools
- Rendering can be slower for large or complex diagrams
Code Comparison
Mermaid example:
graph TD
A[Start] --> B{Is it?}
B -->|Yes| C[OK]
B -->|No| D[End]
Shields example:
![GitHub stars](https://img.shields.io/github/stars/badges/shields.svg?style=social&label=Stars)
![Travis](https://img.shields.io/travis/badges/shields.svg)
Key Differences
- Mermaid focuses on generating diagrams and charts, while Shields creates status badges
- Mermaid uses a custom syntax for describing diagrams, whereas Shields primarily uses URLs and parameters
- Mermaid output is typically SVG-based diagrams, while Shields produces small, informative badges
- Shields is more suitable for quick status indicators, while Mermaid is better for visualizing complex relationships or processes
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
This is home to Shields.io, a service for concise, consistent, and legible badges in SVG and raster format, which can easily be included in GitHub readmes or any other web page. The service supports dozens of continuous integration services, package registries, distributions, app stores, social networks, code coverage services, and code analysis services. Every month it serves over 1.6 billion images and is used by some of the world's most popular open-source projects, VS Code, Vue.js and Bootstrap to name a few.
This repo hosts:
- The Shields.io frontend and server code
- An NPM library for generating badges
- The badge design specification
Examples
- code coverage percentage:
- stable release version:
- package manager release:
- status of third-party dependencies:
- static code analysis grade:
- SemVer version observance:
- amount of Liberapay donations per week:
- Python package downloads:
- Chrome Web Store extension rating:
- Uptime Robot percentage:
Make your own badges!
(Quick example: https://img.shields.io/badge/left-right-f39f37
)
Quickstart
Browse a complete list of badges and locate a particular badge by using the search bar or by browsing the categories. Click on the badge to fill in required data elements for that badge type (like your username or repo) and optionally customize (label, colors etc.). And it's ready for use!
Use the button at the bottom to copy your badge url or snippet, which can then be added to places like your GitHub readme files or other web pages.
Contributing
Shields is a community project. We invite your participation through issues and pull requests! You can peruse the contributing guidelines.
When adding or changing a service please add tests.
This project has quite a backlog of suggestions! If you're new to the project, maybe you'd like to open a pull request to address one of them.
You can read a tutorial on how to add a badge.
If you intend on reporting or contributing a fix related to security vulnerabilities, please first refer to our security policy.
Development
- Install Node 20 or later. You can use the package manager of your choice. Tests need to pass in Node 20 and 22.
- Clone this repository.
- Run
npm ci
to install the dependencies. - Run
npm start
to start the badge server and the frontend dev server. - Open
http://localhost:3000/
to view the frontend.
When server source files change, the badge server should automatically restart
itself (using nodemon). When the frontend files change, the frontend dev
server (docusaurus start
) should also automatically reload. However the badge
definitions are built only before the server first starts. To regenerate those,
either run npm run prestart
or manually restart the server.
To debug a badge from the command line, run npm run badge -- /npm/v/nock
.
It also works with full URLs like
npm run badge -- https://img.shields.io/npm/v/nock
.
Use npm run debug:server
to start server in debug mode.
This recipe shows how to debug Node.js application in VS Code.
Shields has experimental support for Gitpod, a pre-configured development environment that runs in your browser. To use Gitpod, click the button below and sign in with GitHub. Gitpod also offers a browser add-on, though it is not required. Please report any Gitpod bugs, questions, or suggestions in issue #2772.
Snapshot tests ensure we don't inadvertently make changes that affect the
SVG or JSON output. When deliberately changing the output, run
SNAPSHOT_DRY=1 npm run test:package
to preview changes to the saved
snapshots, and SNAPSHOT_UPDATE=1 npm run test:package
to update them.
The server can be configured to use Sentry (configuration) and Prometheus (configuration).
Our full test suite as well as code coverage are run on a daily basis.
Hosting your own server
There is documentation about hosting your own server.
Related projects
Status badges are used widely across open-source and private software projects. Academics have studied the "signal" badges provide about software project quality. There are many existing libraries for rendering these badges, and alternatives to the hosted Shields badge service. awesome-badges is a curated collection of such resources. Contributions may be considered there. (The presence of a project in that collection should not be interpreted as an endorsement nor promotion from the Shields project)
History
b.adge.me was the original website for this service. Heroku back then had a thing which made it hard to use a toplevel domain with it, hence the odd domain. It used code developed in 2013 from a library called gh-badges, both developed by Thaddée Tyl. The project merged with shields.io by making it use the b.adge.me code and closed b.adge.me.
The original badge specification was developed in 2013 by Olivier Lacan. It was inspired by the Travis CI and similar badges (there were a lot fewer, back then). In 2014 Thaddée Tyl redesigned it with help from a Travis CI employee and convinced everyone to switch to it. The old design is what today is called the plastic style; the new one is the flat style.
You can read more about the project's inception, the motivation of the SVG badge specification, and the specification itself.
Project leaders
Maintainers:
- calebcartwright (core team)
- chris48s (core team)
- Daniel15 (core team)
- paulmelnikow (core team)
- platan (core team)
- PyvesB (core team)
- RedSparr0w (core team)
Operations:
Alumni:
License
All assets and code are under the CC0 LICENSE and in the public domain unless specified otherwise.
Community
Thanks to the people and companies who donate money, services or time to keep the project running. https://shields.io/community
Top Related Projects
📈 A small, fast chart for time series, lines, areas, ohlc & bars
Simple HTML5 Charts using the <canvas> tag
Bring data to life with SVG, Canvas and HTML. :bar_chart::chart_with_upwards_trend::tada:
Open-source JavaScript charting library behind Plotly and Dash
📊 Interactive JavaScript Charts built on SVG
Generation of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot