How to Customize the Rank Circle Color and Icon Style in GitHub Readme Stats

You can customize the rank circle color and icon style in GitHub Readme Stats by passing the ring_color and rank_icon query parameters to the stats card API endpoint.

The anuraghazra/github-readme-stats repository generates dynamic SVG stats cards for GitHub profiles. Customizing the rank circle color and icon style allows you to align the card's appearance with your personal branding or preferred metrics display format.

Query Parameters for Rank Customization

The stats card accepts two independent options that control the rank circle's appearance:

Parameter	Controls	Default	Valid Values
ring_color	Hex color of the rank circle stroke (rim and progress arc)	2f80ed	Any valid hex color (3, 4, 6, or 8 digits)
rank_icon	Visual style of the rank indicator	default	default, github, percentile

How the Customization Works Internally

The rendering pipeline processes these parameters through several specialized modules in the codebase.

API Entry Point (api/index.js)

The request handling begins in api/index.js, which extracts query parameters from the URL and forwards them to the card renderer:

// api/index.js extracts ring_color and rank_icon from req.query
const {
  ring_color,
  rank_icon,
  // ... other parameters
} = req.query;

const renderStatsCard = require("../src/cards/stats.js");
// Parameters are passed to renderStatsCard

Color Resolution Logic (src/common/color.js)

Inside renderStatsCard (located in src/cards/stats.js), the function calls getCardColors from src/common/color.js to resolve the ring_color value. The color validation uses a strict regex pattern:

// src/common/color.js
const hexColorValidation = /^([A-Fa-f0-9]{8}|[A-Fa-f0-9]{6}|[A-Fa-f0-9]{3}|[A-Fa-f0-9]{4})$/;

// If valid, the hex string is prefixed with '#' and returned as ringColor
// Falls back to theme color if invalid or omitted

This ensures that only valid hexadecimal colors (3, 4, 6, or 8 digit formats) are injected into the SVG, preventing malformed output.

Icon Style Selection (src/common/icons.js)

The rank_icon parameter determines which SVG fragment renders inside the rank circle. The rankIcon function in src/common/icons.js implements a switch statement:

// src/common/icons.js
const rankIcon = (rankIcon, rankLevel, percentile) => {
  switch (rankIcon) {
    case "github":
      // Returns GitHub logo SVG markup
    case "percentile":
      // Returns "Top xx.x%" text element
    case "default":
    default:
      // Returns the raw rank letter (S, A, B, etc.)
  }
};

SVG Generation and Styling (src/cards/stats.js)

The renderStatsCard function combines these values into the final SVG. The resolved ringColor is injected via the getStyles function into CSS rules targeting the rank circle elements:

/* Generated CSS in the SVG */
.rank-circle-rim { stroke: #ff0000; }
.rank-circle { stroke: #ff0000; }

The inner <g class="rank-text"> element contains the output from rankIcon(rank_icon, rank?.level, rank?.percentile), completing the customization pipeline.

Practical Implementation Examples

Change the Rank Circle Color to Bright Red

Add the ring_color parameter with a hex value (without the # symbol):

[![My stats](https://github-readme-stats.vercel.app/api?username=yourname&ring_color=ff0000)](https://github.com/yourname)

This renders the circle rim and progress arc in #ff0000.

Display the GitHub Logo as the Rank Indicator

Use rank_icon=github to replace the letter grade with the GitHub mark:

[![My stats](https://github-readme-stats.vercel.app/api?username=yourname&rank_icon=github)](https://github.com/yourname)

Show Percentile Instead of Rank Letter

Display your statistical standing (e.g., "Top 12.5%") rather than the letter grade:

[![My stats](https://github-readme-stats.vercel.app/api?username=yourname&rank_icon=percentile)](https://github.com/yourname)

Combine Color and Icon Customization

You can chain both parameters to customize both appearance and content:

[![My stats](https://github-readme-stats.vercel.app/api?username=yourname&ring_color=00ff00&rank_icon=percentile)](https://github.com/yourname)

This produces a green rank circle (#00ff00) displaying the percentile text.

Hide the Rank Circle Entirely

To remove the rank section completely, use the hide_rank parameter:

[![My stats](https://github-readme-stats.vercel.app/api?username=yourname&hide_rank=true)](https://github.com/yourname)

Summary

• ring_color controls the stroke color of the rank circle rim and progress arc, accepting hex values validated in src/common/color.js.
• rank_icon switches between three display modes implemented in src/common/icons.js: letter grade (default), GitHub logo (github), or percentile text (percentile).
• The default color 2f80ed is defined in the theme configuration and applied when no override is provided.
• Invalid hex values gracefully fall back to theme defaults rather than breaking the SVG output.
• All customizations are processed through src/cards/stats.js, which generates the final CSS and SVG structure.

Frequently Asked Questions

What hex color formats does ring_color accept?

The parameter accepts 3-digit (f00), 4-digit (f00f), 6-digit (ff0000), and 8-digit (ff0000ff) hexadecimal formats. The validation regex in src/common/color.js explicitly checks for these patterns before prefixing the value with # and injecting it into the SVG styles.

Can I use CSS color names like "red" or "blue" instead of hex codes?

No. The getCardColors function in src/common/color.js strictly validates against hexadecimal patterns only. CSS named colors are not supported and will cause the renderer to fall back to the default theme color or the theme's predefined ring_color value.

How does the percentile icon calculate the displayed percentage?

The percentile value is calculated during the stats aggregation phase based on your GitHub activity relative to other users. When rank_icon=percentile is specified, the rankIcon function in src/common/icons.js receives the pre-calculated percentile value and formats it as "Top xx.x%" text within the rank circle group.

Is it possible to customize the rank circle color independently of other card elements?

Yes. While themes apply consistent color palettes across the entire card, the ring_color parameter specifically targets the .rank-circle-rim and .rank-circle CSS classes in src/cards/stats.js. This allows you to override only the rank circle stroke color while maintaining the theme's colors for text, backgrounds, and other card elements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}