Shields Getting Started: Generate Your First Badge (2026)

Getting started overview

Shields.io provides a service for generating customizable SVG badges, primarily used to display project status, metrics, or other relevant information within documentation like README.md files. Unlike many API services, Shields.io does not require account creation, API keys, or authentication for its core functionality. Interaction is primarily through constructing a specific URL that defines the badge's content, style, and data source. The service processes this URL and returns an SVG image directly.

The process of getting started with Shields.io involves three main steps:

1. Define Badge Content: Determine the text, color, and optional icon for your badge.
2. Construct URL: Assemble a URL based on Shields.io's conventions, incorporating your desired content and style parameters.
3. Embed Badge: Integrate the generated URL into your project's documentation or web page, typically using an image tag or Markdown image syntax.

This guide focuses on generating a basic static badge, which does not require external data sources. Dynamic badges, which pull data from APIs or web services, follow a similar URL construction pattern but introduce additional parameters for data retrieval.

Getting Started Quick Reference

Create an account and get keys

Shields.io does not require users to create an account or obtain API keys for generating badges. The service is designed for public access and operates by processing URL-based requests directly. This means that any user can generate a badge by constructing the appropriate URL and accessing it through a web browser or embedding it in a document. The absence of an account or key system simplifies the setup process, allowing for immediate use without prior registration or authentication steps.

This model is common for services that provide publicly consumable assets or information where user-specific data or authenticated actions are not involved. For example, many static asset hosts or public data APIs operate without requiring individual user accounts for basic access. The design choice reflects Shields.io's focus on providing a utility for public project visibility rather than a platform for private data management or authenticated interactions.

Your first request

To generate your first badge, you will construct a URL that specifies the badge's content. We will start with a simple static badge, which displays fixed text and color.

Static Badge Structure

A basic static badge URL follows this pattern:

https://img.shields.io/badge/<LABEL>-<MESSAGE>-<COLOR>

• <LABEL>: The text displayed on the left side of the badge.
• <MESSAGE>: The text displayed on the right side of the badge.
• <COLOR>: The background color of the message section. Shields.io supports named colors (e.g., blue, green) and hexadecimal color codes (e.g., %234c1 for #4c1). Note that hexadecimal codes must be URL-encoded.

Example: Basic Static Badge

Let's create a badge that says "Status" on the left, "Active" on the right, with a green background for the message.

https://img.shields.io/badge/Status-Active-green

To generate this badge, copy and paste the URL into your web browser's address bar and press Enter. The browser will display an SVG image of the badge. Alternatively, you can use a command-line tool like curl to fetch the SVG content:

curl -o status-badge.svg "https://img.shields.io/badge/Status-Active-green"

This command saves the generated SVG badge to a file named status-badge.svg in your current directory.

Embedding the Badge

Once you have the URL, you can embed the badge into your project's documentation or web page. For most README.md files on platforms like GitHub or GitLab, Markdown syntax is used:

![Project Status](https://img.shields.io/badge/Status-Active-green)

If you are embedding the badge into an HTML page, use an <img> tag:

<img src="https://img.shields.io/badge/Status-Active-green" alt="Project Status">

The alt attribute provides alternative text for accessibility and when the image cannot be displayed. For more details on image embedding in HTML, refer to the Mozilla Developer Network's <img> element documentation.

Common next steps

After successfully generating and embedding your first static badge, several common next steps can enhance your project's badging:

1. Explore Dynamic Badges

Shields.io's primary strength lies in its ability to generate dynamic badges that reflect real-time data from various services. These badges automatically update when the underlying data changes. Examples include:

• Build Status: Integrating with CI/CD services like Jenkins, Travis CI, or GitHub Actions to show the current build status.
• Package Version: Displaying the latest version of a package from npm, PyPI, or Maven Central.
• Code Coverage: Showing code coverage metrics from services like Codecov or Coveralls.
• License Information: Automatically pulling license types from project repositories.

The Shields.io documentation provides extensive examples and templates for integrating with hundreds of services. Each service typically has a specific URL pattern that includes identifiers like repository names or package IDs.

2. Customize Badge Appearance

Shields.io offers several parameters to customize the visual appearance of your badges:

• Style: Choose from various styles like flat, flat-square, for-the-badge, or plastic. Add ?style=<style_name> to your URL (e.g., https://img.shields.io/badge/Status-Active-green?style=for-the-badge).
• Icons: Include an icon from Simple Icons by adding ?logo=<icon_name> (e.g., ?logo=github).
• Color: Use specific hexadecimal color codes for precise branding (e.g., ?color=FF0000).
• Link: Make the badge clickable by adding ?link=<URL>.

These customization options allow you to align badges with your project's branding or personal preferences. For a complete list of customization parameters, consult the Shields.io style and customization documentation.

3. Create Custom Dynamic Badges

For data sources not natively supported by Shields.io, you can create a custom dynamic badge by providing a JSON endpoint. This allows you to display any data accessible via a public API. The general structure for a custom dynamic badge URL is:

https://img.shields.io/badge/dynamic/json?url=<JSON_URL>&query=<JSON_PATH>&label=<LABEL>&color=<COLOR>

• url: The URL of your JSON data source.
• query: A JSONPath expression to extract the desired value from the JSON response.
• label: The text for the left side of the badge.
• color: The background color for the message section.

This advanced feature provides flexibility for integrating with bespoke APIs or internal metrics systems. An example of JSONPath usage can be found in the IETF JSONPath Base specification.

4. Self-Hosting Shields

For organizations with specific security or performance requirements, or those who prefer to maintain full control over their badge generation, Shields.io can be self-hosted. The project is open-source, and its codebase is available on GitHub. Self-hosting involves deploying the Shields.io application on your own infrastructure. This option is typically considered by larger organizations or projects with high traffic volumes that need custom modifications or guaranteed uptime outside of the public service.

Troubleshooting the first call

When your first Shields.io badge doesn't appear as expected, consider these common troubleshooting steps:

1. Verify URL Syntax

The most frequent issue is incorrect URL syntax. Double-check:

• Slashes and Hyphens: Ensure correct placement of / and -.
• URL Encoding: Spaces in labels or messages must be replaced with %20 or _. Hexadecimal color codes need %23 instead of #.
• Parameter Order: While flexible for static badges, dynamic badges often have specific parameter requirements.
• Correct Domain: Ensure you are using https://img.shields.io/.

Refer to the Shields.io documentation on URL construction for exact syntax rules.

2. Check for Typos

Even small typos in labels, messages, or color names can prevent a badge from rendering. For example, grean instead of green will result in a default gray badge or an error.

3. Test in Browser Directly

Paste the full badge URL directly into your web browser's address bar. If the browser displays a broken image or an error message, the issue is with the URL itself, not how it's embedded. If it displays correctly in the browser but not in your README.md, the embedding syntax (e.g., Markdown or HTML) might be incorrect.

4. Inspect Network Requests (Browser Developer Tools)

When embedding a badge in a web page or a platform that renders HTML (like GitHub's Markdown preview), use your browser's developer tools (usually F12) to inspect network requests. Look for the request to img.shields.io. Check the HTTP status code:

• 200 OK: The badge was successfully generated and returned.
• 400 Bad Request: Indicates an issue with your URL parameters.
• 404 Not Found: Often occurs with dynamic badges if the upstream service or resource isn't found.
• 5xx Server Error: Less common, but indicates an issue on the Shields.io server.

The response body or headers might contain more specific error messages.

5. Dynamic Badge Specifics

If you are using a dynamic badge:

• Upstream Service Status: Verify that the service Shields.io is trying to query (e.g., npm, GitHub, Travis CI) is operational and accessible.
• Correct Identifiers: Ensure you've provided the correct repository name, package ID, or API endpoint.
• Public Accessibility: For custom dynamic badges, ensure your JSON url is publicly accessible and returns valid JSON. Shields.io cannot access private endpoints.
• JSONPath Validity: For custom dynamic badges, confirm your JSONPath expression correctly extracts the desired value. Tools like online JSONPath testers can help validate expressions.

By systematically checking these points, you can identify and resolve most issues encountered when generating your first Shields.io badge.