How to display different images for GitHub light mode and dark mode

Learn how to make your images automatically adapt to light and dark themes on GitHub README using Markdown and HTML, especially for company/project logos.

Method 1: The GitHub-Specific URL Fragment

GitHub provides a simple, Markdown-native way to specify theme-based images by appending a fragment to the image URL. You provide two separate images, and GitHub's frontend displays the appropriate one based on the current theme.

• #gh-light-mode-only
• #gh-dark-mode-only

Here’s how you implement it. Notice you are essentially writing two separate Markdown image links on the same line.

<!-- The light mode image is followed by the dark mode image -->
![My Alt Text](https://path/to/your/image-light.png#gh-light-mode-only)
![My Alt Text](https://path/to/your/image-dark.png#gh-dark-mode-only)

Pros:

• Pure Markdown: No HTML required. It keeps your files clean and simple.
• Easy to Remember: The syntax is straightforward and semantic.

Cons:

• GitHub Only: This is a proprietary GitHub feature. It will not work on other Markdown platforms like GitLab, Bitbucket, or most static site generators. But also, you're doing this for your public GitHub Project.

Method 2: The HTML <picture> Element

For a more universal, web-standard solution, you can embed an HTML <picture> element directly into your Markdown file. This method uses the prefers-color-scheme CSS media feature to serve the correct image.

<picture>
  <!-- Source for dark mode -->
  <source media="(prefers-color-scheme: dark)" srcset="https://path/to/your/image-dark.png">
  <!-- Fallback image for light mode and other clients -->
  <img alt="My Alt Text" src="https://path/to/your/image-light.png">
</picture>

Pros:

• Web Standard: This approach works in most modern browsers and on any platform that correctly renders HTML within Markdown.
• More Flexible: The <picture> element can be extended with more sources for different themes, screen sizes, or image formats.

Cons:

• Requires HTML: It introduces HTML into your Markdown.
• More Verbose: The extra syntax/code for just an image. As the number of images grows, the README.md will be bloated.

Common Pitfalls

1. Browser Caching: If you're testing and the image doesn't switch, it might be a caching issue. Try a hard refresh (Ctrl+Shift+R or Cmd+Shift+R) or view the page in an incognito window.
2. Unsupported Platforms: Remember that the fragment method is GitHub-specific. If your Markdown is rendered elsewhere, it will likely show both images stacked on top of each other.

References : 1, 2

This blog stems from my need to find a way to render dark/light images on my GitHub project. And I'll document this for everyone.

Feel free to reach out to me if you have any questions:

• LinkedIn
• GitHub
• X/Twitter

DMs are open, and I'm happy to help.

Comments

[Suvrajeet Banerjee]

Theme aware! 🎨

[𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒]

Yes 🙌

[Yafuso Bera]

<source media="(prefers-color-scheme: dark)" srcset="https://path/to/your/image-dark.png">

Do you need to add a :light in here as well? To specify the image for the light theme?

[𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒]

So, one will be chosen as the default, and the other will be activated when on a dark theme. But yes, you can manually specify dark and light by having two source tags.

[Data with Johnson]

Really useful

[𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒]

Thank you

[Louis Liu]

I love this post, it's concise and useful!

[𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒]

Thank you. Usefulness was the goal here.

[OPEN READ]

nice post

[𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒]

Thank you

[fast-d3v]

Hah, this was simpler. I use neutral colors like gray-500 with a transparent png to match things.

[𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒]

Well you could have vibecoded a react framework instead.

[Best Codes]

Thanks for this super useful short little post! I've often wondered how to do this.

[𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒]

You're welcome.