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

> Customize your GitHub Readme Stats rank circle color and icon style using simple query parameters. Enhance your profile's visual appeal today.

- Repository: [Anurag Hazra/github-readme-stats](https://github.com/anuraghazra/github-readme-stats)
- Tags: how-to-guide
- Published: 2026-02-28

---

**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`](https://github.com/anuraghazra/github-readme-stats/blob/main/api/index.js))

The request handling begins in [`api/index.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/api/index.js), which extracts query parameters from the URL and forwards them to the card renderer:

```javascript
// 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`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/color.js))

Inside `renderStatsCard` (located in [`src/cards/stats.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/cards/stats.js)), the function calls `getCardColors` from [`src/common/color.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/color.js) to resolve the `ring_color` value. The color validation uses a strict regex pattern:

```javascript
// 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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/icons.js) implements a switch statement:

```javascript
// 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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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:

```css
/* 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):

```markdown
[![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:

```markdown
[![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:

```markdown
[![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:

```markdown
[![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:

```markdown
[![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`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/color.js).
- **`rank_icon`** switches between three display modes implemented in [`src/common/icons.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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.