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

> Customize your GitHub Readme Stats with transparent themes or add your own custom themes easily. Learn how to integrate unique designs into your profile.

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

---

**Use the `&theme=transparent` query parameter to render cards with a transparent background, or add a new theme object to [`themes/index.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/index.js) and looks up the corresponding color object in [`themes/index.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`:

```javascript
// 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.

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

```markdown
![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`](https://github.com/anuraghazra/github-readme-stats/blob/main/themes/index.js) and submitting a pull request. The repository includes automated validation via [`scripts/preview-theme.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`:

```javascript
// 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`](https://github.com/anuraghazra/github-readme-stats/blob/main/scripts/preview-theme.js), which utilizes validation functions from [`src/common/color.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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.

```markdown
[![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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/themes/index.js)
- **Custom themes**: Add new entries to [`themes/index.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/themes/index.js) using snake_case keys and 6-digit hex colors, then submit a PR for validation via [`scripts/preview-theme.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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.