# How to Show Dark/Light Mode Responsive Cards in GitHub Readme Stats

> Learn how to create dark/light mode responsive cards for your GitHub Readme Stats using theme context tags or HTML picture elements. Enhance your profile with dynamic styling.

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

---

**Use GitHub's theme context tags (`#gh-dark-mode-only`/`#gh-light-mode-only`) for markdown-only solutions, or employ HTML `<picture>` elements with `prefers-color-scheme` media queries to serve dark/light mode responsive cards with a single network request.**

The **anuraghazra/github-readme-stats** repository generates customizable SVG statistic cards that can be embedded in any README. To make these cards automatically adapt to a viewer's GitHub interface theme, you must explicitly configure the embedding markup to reference different theme parameters based on the user's dark or light mode preference.

## Method 1: Using GitHub Theme Context Tags (Markdown-Only)

GitHub supports special URL fragments that conditionally render images based on the user's interface theme. This approach requires no HTML and works entirely within standard markdown.

### Implementing Theme Context Fragments

Append `#gh-dark-mode-only` or `#gh-light-mode-only` to your image URLs. GitHub's markdown renderer will display the appropriate image only when the viewer's UI matches the specified theme.

```markdown
[![My Stats – Dark](https://github-readme-stats.vercel.app/api?username=YOUR_USER&show_icons=true&theme=dark#gh-dark-mode-only)](https://github.com/YOUR_USER/github-readme-stats#gh-dark-mode-only)
[![My Stats – Light](https://github-readme-stats.vercel.app/api?username=YOUR_USER&show_icons=true&theme=default#gh-light-mode-only)](https://github.com/YOUR_USER/github-readme-stats#gh-light-mode-only)

```

- The first link renders **only** when the viewer uses dark mode.
- The second link renders **only** when the viewer uses light mode.
- Both cards load independently; the browser requests both images but displays only the matching one.

According to the repository documentation in [`readme.md`](https://github.com/anuraghazra/github-readme-stats/blob/main/readme.md) (lines 21-23), this is the simplest implementation for pure markdown files.

## Method 2: Using HTML Picture Elements with Media Queries

For optimal performance and single-request loading, use the HTML5 `<picture>` element with `<source>` tags targeting the `prefers-color-scheme` media feature. GitHub-flavored markdown supports embedded HTML, allowing this standard browser API to control which card variant loads.

### Adaptive Rendering with Prefers-Color-Scheme

```html
<picture>
  <source srcset="https://github-readme-stats.vercel.app/api?username=YOUR_USER&show_icons=true&theme=dark"
          media="(prefers-color-scheme: dark)" />
  <source srcset="https://github-readme-stats.vercel.app/api?username=YOUR_USER&show_icons=true"
          media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" />
  <img src="https://github-readme-stats.vercel.app/api?username=YOUR_USER&show_icons=true"
       alt="GitHub Readme Stats" />
</picture>

```

- The browser evaluates the media queries and requests **only** the appropriate `srcset` URL.
- The fallback `<img>` tag ensures compatibility if media query support is absent.
- As documented in [`readme.md`](https://github.com/anuraghazra/github-readme-stats/blob/main/readme.md) (lines 37-48), this method provides finer layout control and reduces unnecessary network requests compared to the fragment-based approach.

## Optimizing with Transparent Backgrounds

For seamless integration regardless of theme, set a fully transparent background using the `bg_color` parameter. This allows the card to inherit the README's background color, eliminating visual clashes when GitHub's theme changes.

```markdown
![Stats with transparent background](https://github-readme-stats.vercel.app/api?username=YOUR_USER&show_icons=true&bg_color=00000000)

```

The value `00000000` represents 8-digit hexadecimal RGBA with zero alpha. The color parsing logic in [`src/common/color.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/color.js) handles this parameter, while [`src/common/Card.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/Card.js) (line 227) applies it to the SVG template during server-side rendering.

## Technical Implementation in the Source Code

Understanding how the repository processes themes ensures you implement responsive cards correctly.

### Theme Selection Architecture

- **[`src/common/Card.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/Card.js)** – Contains the SVG generation logic. The `theme` query parameter directly controls color variables injected into the card template at line 227.
- **[`themes/index.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/themes/index.js)** – Defines all built-in color schemes (including `dark` and `default` light themes) available via the `theme` parameter.
- **[`readme.md`](https://github.com/anuraghazra/github-readme-stats/blob/main/readme.md)** (lines 16-49) – Documents both responsive techniques with complete markup examples, explaining the trade-offs between fragment-based and media-query approaches.

The API endpoint is a server-side Express application that generates static SVGs; no client-side code executes within the card itself, making theme selection entirely dependent on the URL parameters you specify in your embedding markup.

## Summary

- **Theme context tags** (`#gh-dark-mode-only`/`#gh-light-mode-only`) provide the simplest markdown-only implementation but load both image variants.
- **HTML `<picture>` elements** with `prefers-color-scheme` media queries offer superior performance by requesting only the appropriate theme variant.
- **Transparent backgrounds** (`bg_color=00000000`) allow cards to blend with any GitHub theme without manual theme switching.
- The `theme` query parameter controls colors defined in [`themes/index.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/themes/index.js) and rendered by [`src/common/Card.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/Card.js).

## Frequently Asked Questions

### Can I use a custom theme with dark/light mode responsive cards?

Yes. Replace `theme=dark` or `theme=default` with any supported theme name from [`themes/index.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/themes/index.js) (such as `radical`, `merko`, or `gruvbox`) in your dark or light mode URLs. The responsive mechanism only controls which URL loads, not the specific theme assigned to that URL.

### Why are my cards not switching themes automatically on GitHub?

Ensure you have implemented either the URL fragment tags (`#gh-dark-mode-only`) or the `<picture>` element media queries correctly. If using fragments, verify that you have included **both** image links in your markdown—GitHub hides the non-matching link entirely, so omitting one means no card appears for that theme. If using `<picture>`, confirm your `media` attributes match `(prefers-color-scheme: dark)` exactly.

### Does the `<picture>` element method reduce API requests compared to fragment tags?

Yes. The fragment tag approach causes the browser to load both image URLs (dark and light variants) regardless of which one displays, though GitHub hides the non-matching image via CSS. The `<picture>` element method requests only the single `srcset` URL that matches the user's `prefers-color-scheme` preference, reducing bandwidth and API load by half for each visitor.

### How do I set a completely transparent background for better theme adaptation?

Append `&bg_color=00000000` to your API URL. This 8-digit hex color sets the alpha channel to transparent in the SVG generated by [`src/common/Card.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/Card.js), allowing the card to inherit the GitHub interface's actual background color and eliminating visible borders when switching between dark and light modes.