How to Add Custom Themes or Use the Transparent Theme in GitHub Readme Stats

Use the &theme=transparent query parameter to render cards with a transparent background, or add a new theme object to themes/index.js and submit a pull request to contribute custom themes.

GitHub Readme Stats generates SVG cards that can be customized via URL parameters. The repository anuraghazra/github-readme-stats provides a built-in theme system defined in themes/index.js, allowing users to select from pre-defined color palettes or override individual colors for complete customization.

Understanding the Theme System in GitHub Readme Stats

The theme engine operates by merging color values into the card's SVG rendering pipeline. When the API receives a request, it reads the theme query parameter from src/index.js and looks up the corresponding color object in themes/index.js.

Each theme is a JavaScript object containing hex color values for specific card elements:

• title_color: The username and card title
• icon_color: Icons for stars, forks, and commits
• text_color: General statistics text
• bg_color: Background color (supports RGBA for transparency)
• border_color: Optional card border (optional)

The transparent theme is pre-defined with a fully transparent background using the hex value ffffff00:

// https://github.com/anuraghazra/github-readme-stats/blob/master/themes/index.js#L15-L20
transparent: {
  title_color: "006AFF",
  icon_color: "0579C3",
  text_color: "417E87",
  bg_color: "ffffff00",
},

How to Use the Transparent Theme in Your GitHub Profile

To apply the transparent background to your stats card, append &theme=transparent to the API URL. This renders the card without a background color, allowing it to blend seamlessly with both GitHub's light and dark UI themes.

![My GitHub Stats](https://github-readme-stats.vercel.app/api?username=YOUR_USERNAME&show_icons=true&theme=transparent)

Making Any Theme Transparent with RGBA Overrides

You can also make any existing theme transparent without creating a new theme entry by overriding the bg_color parameter with an RGBA hex code that includes an alpha channel of 00:

![Transparent Dark Theme](https://github-readme-stats.vercel.app/api?username=YOUR_USERNAME&show_icons=true&theme=dark&bg_color=00000000)

This technique works because the bg_color parameter takes precedence over the theme's default background color in the rendering pipeline.

How to Add Custom Themes to GitHub Readme Stats

Contributing a new theme requires modifying themes/index.js and submitting a pull request. The repository includes automated validation via scripts/preview-theme.js that checks color format, contrast ratios, and naming conventions.

Follow these steps to add a custom theme:

1. Fork the anuraghazra/github-readme-stats repository
2. Open themes/index.js
3. Add a new entry using snake_case for the theme key (enforced by CI)
4. Define the required color properties using 6-digit hex codes
5. Optionally include border_color for additional styling

Example of adding a custom theme called ocean_dark:

// https://github.com/anuraghazra/github-readme-stats/blob/master/themes/index.js
ocean_dark: {
  title_color: "58a6ff",
  icon_color: "58a6ff",
  text_color: "c9d1d9",
  bg_color: "0d1117",
  border_color: "30363d",
},

After committing your changes, the CI pipeline runs scripts/preview-theme.js, which utilizes validation functions from src/common/color.js (including isValidHexColor and isValidGradient) to ensure your theme meets the repository's quality standards before merging.

Advanced Theme Customization Techniques

GitHub Theme Context Awareness

You can combine the transparent theme with GitHub's theme context tags to display different cards for light and dark mode users. This ensures optimal contrast regardless of the user's GitHub appearance settings.

[![Light Mode Stats](https://github-readme-stats.vercel.app/api?username=YOUR_USER&theme=default#gh-light-mode-only)](https://github.com/anuraghazra/github-readme-stats)
[![Dark Mode Stats](https://github-readme-stats.vercel.app/api?username=YOUR_USER&theme=transparent#gh-dark-mode-only)](https://github.com/anuraghazra/github-readme-stats)

Validating Color Contrast

When adding custom themes, ensure sufficient contrast between text_color and bg_color for accessibility. The automated validator in scripts/preview-theme.js checks these values, but manual verification ensures your card remains readable across different displays.

Summary

• Transparent theme: Use &theme=transparent to render cards with bg_color: "ffffff00" defined in themes/index.js
• Custom themes: Add new entries to themes/index.js using snake_case keys and 6-digit hex colors, then submit a PR for validation via scripts/preview-theme.js
• RGBA overrides: Append &bg_color=00000000 to any theme to force transparency without modifying source files
• Theme context: Combine #gh-light-mode-only and #gh-dark-mode-only tags with different themes for adaptive rendering

Frequently Asked Questions

What is the transparent theme in GitHub Readme Stats?

The transparent theme is a built-in color scheme defined in themes/index.js that sets the background color to fully transparent using the hex value ffffff00. When you use &theme=transparent in your API URL, the rendered SVG card has no background fill, allowing it to blend seamlessly with both GitHub's light and dark user interfaces.

How do I make my GitHub stats card background transparent?

You have two methods to achieve transparency. First, you can use the built-in transparent theme by adding &theme=transparent to your image URL. Alternatively, you can override any theme's background color by appending &bg_color=00000000 (or any RGBA hex with 00 alpha) to the URL, which forces transparency without changing the theme definition in themes/index.js.

Can I contribute a new theme to the GitHub Readme Stats repository?

Yes, you can contribute custom themes by submitting a pull request. To do this, fork the repository, add your theme to themes/index.js using snake_case naming, and define the required color properties (title_color, icon_color, text_color, bg_color). The CI pipeline automatically runs scripts/preview-theme.js to validate hex formats, contrast ratios, and naming conventions before merging.

How do I show different themes for GitHub light and dark mode?

You can use GitHub's theme context tags (#gh-light-mode-only and #gh-dark-mode-only) combined with different theme parameters. Create two separate image links—one with a light theme for gh-light-mode-only and one with theme=transparent or a dark theme for gh-dark-mode-only. This ensures your stats card maintains optimal contrast regardless of the user's GitHub appearance settings.

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