# How to Configure Custom Colors and Gradients on GitHub Readme Stats Cards

> Customize GitHub Readme Stats cards with custom colors and gradients. Learn to use hex values and gradient syntax to personalize your stats.

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

---

**You can customize GitHub Readme Stats cards by appending URL query parameters like `title_color`, `bg_color`, and `icon_color` to the API endpoint, using either solid hex values or gradient definitions with the syntax `ANGLE,HEX1,HEX2`.**

The `anuraghazra/github-readme-stats` repository generates dynamic SVG cards for GitHub profiles and repositories. By manipulating specific query parameters, you can override default theme colors and apply custom gradients to match your personal branding or GitHub profile aesthetic.

## How Color Configuration Works in the Source Code

The customization system follows a four-stage pipeline implemented in the source code:

1. **Parameter Parsing**: The API extracts color-related query parameters including `title_color`, `icon_color`, `text_color`, `bg_color`, and `border_color`.

2. **Validation**: In [`src/common/color.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/color.js), the `isValidHexColor` function validates hex strings while `isValidGradient` detects gradient definitions. The `fallbackColor` function returns an array for gradients where the first element is the **angle** and subsequent items are hex color stops.

3. **Theme Merging**: The `getCardColors` function overlays user-provided values on top of the selected theme (e.g., `default`, `radical`, `transparent`) from [`themes/index.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/themes/index.js) and falls back to theme defaults when values are missing or invalid.

4. **SVG Rendering**: In [`src/common/Card.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/Card.js), the code checks if `bgColor` is an object (gradient array). If so, it injects a `<linearGradient>` definition with the specified angle and color stops, then applies it via `fill="url(#gradient)"`.

## Available Color Parameters

You can override any of these color values via query string:

- `title_color`: Card title text
- `text_color`: Body text and statistics  
- `icon_color`: Icons and rank badges
- `bg_color`: Background color or gradient definition
- `border_color`: Card border color

All values accept 3, 4, 6, or 8-digit hex codes **without** the leading `#`.

## Gradient Syntax and Validation

For gradients, use the `bg_color` parameter with comma-separated values:

```

bg_color=ANGLE,HEX1,HEX2[,HEX3...]

```

- **ANGLE**: Integer degrees for rotation (0-360)
- **HEXn**: Color stops without `#` prefix

The `isValidGradient` function in [`src/common/color.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/color.js) validates that the string contains more than two comma-separated entries where all hex values pass `isValidHexColor`. If validation fails, the system falls back to a solid color via `fallbackColor`.

## Practical Configuration Examples

### Solid Color Overrides

Override individual elements with specific hex values:

```md
![GitHub Stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&title_color=fff&icon_color=79ff97&text_color=9f9f9f&bg_color=151515&border_color=2e4058)

```

This sets a near-black background (`151515`) with white titles and teal icons.

### Two-Color Linear Gradient

Create a 30-degree gradient from orange to purple:

```md
![GitHub Stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&bg_color=30,e96443,904e95&title_color=fff&text_color=fff)

```

The `30` specifies the rotation angle, while `e96443` and `904e95` define the color stops.

### Multi-Stop Gradients

Add multiple color stops for complex gradients:

```md
![GitHub Stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&bg_color=45,ff7e5f,feb47b,ffefba,ffffff&title_color=000&text_color=333)

```

This creates a 45-degree gradient with four color transitions.

### Combining Themes with Custom Backgrounds

Use a built-in theme while overriding only the background:

```md
![GitHub Stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&theme=radical&bg_color=0,ff5f6d,ffc371)

```

The `getCardColors` function merges the `radical` theme defaults with your gradient specification.

### Transparent Backgrounds

For GitHub's light/dark mode compatibility:

```md
![GitHub Stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&bg_color=00000000&theme=transparent)

```

The 8-digit hex `00000000` sets the alpha channel to fully transparent.

## Summary

- Append color parameters to the API URL to override theme defaults from [`themes/index.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/themes/index.js)
- The [`src/common/color.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/color.js) validation logic ensures only safe hex values and proper gradient syntax are rendered
- Specify gradients in `bg_color` using the format `ANGLE,COLOR1,COLOR2`
- The rendering logic in [`src/common/Card.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/Card.js) converts valid gradient arrays into SVG `<linearGradient>` definitions
- Use 8-digit hex codes (with alpha channel) to create transparent backgrounds that adapt to GitHub's color modes

## Frequently Asked Questions

### How many color stops can I use in a gradient?

The validation logic in [`src/common/color.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/color.js) accepts any number of hex values after the angle parameter. While the code imposes no hard limit, practical SVG rendering suggests keeping stops under 10 for optimal performance and file size.

### Can I use RGB or HSL values instead of hex?

No. The `isValidHexColor` function strictly validates 3, 4, 6, or 8-digit hex codes. RGB, HSL, or named colors will fail validation and trigger the `fallbackColor` mechanism, which returns the theme default.

### Why does my gradient show as a solid color instead?

This occurs when the gradient string fails validation in `isValidGradient`. Common causes include: including the `#` symbol in hex values, omitting the angle parameter, providing fewer than two color stops, or using invalid hex digits. The system falls back to the theme's default background color when validation fails.

### Do custom colors work with all card types?

Yes. The color configuration system in [`src/common/Card.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/Card.js) is shared across all card types including the stats card and top languages card. The `getCardColors` function processes parameters uniformly regardless of which specific endpoint generates the SVG.