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

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, 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 and falls back to theme defaults when values are missing or invalid.

4. SVG Rendering: In 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 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:

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

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

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

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

![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
• The 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 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 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 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.

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