GitHub supports dark mode and light mode, and as developers, we can make our README images look great in both themes. Here’s a quick guide to using the <picture> element in your GitHub Markdown files to dynamically switch images based on the user’s color scheme.

When users switch to GitHub’s dark mode (or vice versa), standard images can look out of place, with bright backgrounds or clashing colors.

Instead of forcing a one-size-fits-all image, you can tailor your visuals to blend seamlessly with the theme. It’s a small change, but it can make your project look much more polished.

One snippet, two themes!

Here’s the magic snippet you can copy into your README (or any Markdown file):

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="dark-mode-image.png">
  <source media="(prefers-color-scheme: light)" srcset="light-mode-image.png">
  <img alt="Fallback image description" src="default-image.png">
</picture>

Now, we say it’s magic, but let’s take a peek behind the curtain on how it works:

The <picture> tag lets you define multiple image sources for different scenarios.
The <source media="..."> attribute matches the user’s color scheme.
- When media="(prefers-color-scheme: dark)", the browser loads the srcset image when GitHub is in dark mode.
- Similarly, when media="(prefers-color-scheme: light)", the browser loads the srcset image when GitHub is in light mode.
If the browser doesn’t support the <picture> element, or the user’s system doesn’t match any defined media queries, the fallback <img> tag will be used.

You can use this approach in your repo README files, documentation hosted on GitHub, and any other Markdown files rendered on GitHub.com!

Demo

Check out the gist here for a demo of how an image can change between dark mode and light mode on your profiles, READMEs, and moooore.

Until next time!