# Adding preview screenshots to Discourse themes
**URL:** https://meta.discourse.org/t/adding-preview-screenshots-to-discourse-themes/365083
**Category:** Developer Guides
**Created:** [2025年五月7日 03:35 UTC](https://meta.discourse.org/t/adding-preview-screenshots-to-discourse-themes/365083 "2025-05-07T03:35:21Z")
**Posts on this page:** 4
**Page:** 1
### Author:  [@system](https://meta.discourse.org/u/system)
#### Post date: [2025年五月7日 03:35 UTC](https://meta.discourse.org/t/adding-preview-screenshots-to-discourse-themes/365083/1 "2025-05-07T03:35:21Z")
> 🔖 This guide explains how to add preview screenshots to your Discourse theme to showcase how it looks in both light and dark modes.
>
> 🙋 Required user: Theme developers
Adding preview screenshots to your Discourse theme helps users quickly understand how your theme looks before they install it. This guide will walk you through adding light and dark mode screenshots to your theme.
## Creating the screenshots folder
To add preview screenshots to your theme:
1. Create a folder called `screenshots` in the root directory of your theme
2. Add two image files to this folder:
- `light.webp` - Shows your theme in light mode
- `dark.webp` - Shows your theme in dark mode
## Setting up the image files
Your screenshot images must meet these requirements:
- **Ratio** : 16:9 aspect ratio
- **Dimensions** : 2560 × 1440 pixels (recommended)
- **File size** : Under 1MB per image
- **Format** : WebP, PNG, JPEG
> ℹ Using the recommended dimensions ensures your screenshots look crisp on high-resolution displays while maintaining reasonable file sizes.
## Updating the about.json file
After creating your screenshots, you need to update your theme’s `about.json` file to include references to these images:
1. Open your theme’s `about.json` file
2. Add the `screenshots` array to the JSON object:
```json
"screenshots": ["screenshots/light.webp", "screenshots/dark.webp"]
```
## Best practices for theme screenshots
### Capturing your theme
When taking screenshots of your theme:
- Show the main interface components that make your theme unique.
- Include examples of your theme’s color palette and typography.
- Ensure both screenshots show the same view for easy comparison.
- Use realistic content rather than placeholder text where possible.
### Image optimization
Keep your images under the 1MB size limit by:
- Using WebP format, as it combines the advantages of JPEG and PNG, offering more efficient compression than both.
- For PNG format, using optimization tools like [TinyPNG](https://tinypng.com/) or [ImageOptim](https://imageoptim.com/).
- Removing unnecessary metadata from image files.
- Considering slightly reduced dimensions if needed while maintaining the 16:9 ratio.
## Common issues and solutions
### Images not appearing in theme preview
**Issue** : Screenshots don’t appear when viewing the theme in the admin panel.
**Solution** : Verify that:
1. Your file names in `about.json` exactly match the actual file names (these are case-sensitive).
2. The images are properly uploaded to the theme’s repository in the `screenshots` folder.
### File size too large
**Issue** : Image files exceed the 1MB limit.
**Solution** :
1. Use image optimization tools to reduce file size.
2. Reduce image dimensions while maintaining the 16:9 ratio.
3. Consider using a more efficient compression method.
## FAQs
**Q: Do I need both light and dark screenshots?**
A: It is not required, but it’s good practice to include both light and dark screenshots. If you only include one, the same image will be displayed for both light and dark schemes. If no image is provided at all, a fallback will be displayed.
**Q: Can I use a different image format than PNG?**
A: PNG is recommended for its balance of quality and size. While other formats might work, PNG is the standard for Discourse theme screenshots.
**Q: How do I take good screenshots of my theme?**
A: Use a full-screen browser window at 2560×1440 resolution with developer tools closed. Set your theme to light mode for one screenshot and dark mode for the other.
## Additional resources
- [Beginner's guide to using Discourse Themes](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966)
- [Developing Discourse Themes & Theme Components](https://meta.discourse.org/t/developer-s-guide-to-discourse-themes/93648)
* * *
This document is version controlled - suggest changes [on github](https://github.com/discourse/discourse/blob/main/docs/developer-guides/docs/05-themes-components/34-theme-screenshots.md).
---
### Author:  [@manuel](https://meta.discourse.org/u/manuel)
#### Post date: [2025年六月3日 12:41 UTC](https://meta.discourse.org/t/adding-preview-screenshots-to-discourse-themes/365083/2 "2025-06-03T12:41:22Z")
我猜暗色截图应该在我处于暗黑模式时显示？对我来说它不起作用，不确定这是个 bug 还是我遗漏了什么。
---
### Author:  [@Moin](https://meta.discourse.org/u/Moin)
#### Post date: [2025年七月16日 08:12 UTC](https://meta.discourse.org/t/adding-preview-screenshots-to-discourse-themes/365083/3 "2025-07-16T08:12:00Z")
我注意到类似的情况。在浅色模式下我看到了深色版本。
---
### Author:  [@rsigg](https://meta.discourse.org/u/rsigg)
#### Post date: [2026年二月18日 22:41 UTC](https://meta.discourse.org/t/adding-preview-screenshots-to-discourse-themes/365083/4 "2026-02-18T22:41:48Z")
上传截图时，我收到了以下消息：
> 发生错误：主题截图的最大尺寸为 3840x2160。截图 dark.webp 超出了此限制。其尺寸为 4004x2024。
也许可以在这些文档中提及此最大值？
**编辑：** 另外，它似乎也不关心 `16:9 宽高比`
我将图片尺寸减小到 `3840 × 1941` 后，它就可以正常工作了。