How to add a theme preview in Shopware

By Daniel Bohusz, Shopware developer since 2014 · Published 25 February 2026 · Updated October 2026

Your custom theme shows an empty tile under Sales Channels > Themes in the Shopware Administration? Two things are needed: the image in the right folder of your theme plugin, and the previewMedia key in theme.json pointing to it.

Short answer – put the image in src/Resources/app/storefront/src/assets/ and add this line to src/Resources/theme.json:

"previewMedia": "app/storefront/src/assets/your-theme-name-preview.jpg"

The path is relative to the Resources folder. The steps below explain the details and the most common reasons the preview does not appear.

In the Administration, themes are shown as a gallery. Without a preview image your theme is a grey tile, which is confusing when several themes are installed and looks unfinished if you deliver the theme to a client or sell it in the Shopware Store.

A preview image:

• helps shop staff pick the right theme quickly
• avoids mix-ups when several themes are installed
• makes a theme you deliver to clients or publish in the Shopware Store look complete

A Shopware theme is a plugin. Shopware reads the theme metadata, including the preview image, from theme.json in the Resources folder of the plugin. The official Shopware theme configuration docs describe all keys of this file.

Two things must be right: the image has to be in a folder that is included when the plugin is packaged, and previewMedia has to point to it with the correct relative path. Most missing previews come from one of these two.

Step 1: Prepare the image

Use the same proportions as the default Storefront preview. 1920 × 1080 pixels, or a similar wide format, works well. Save it as .jpg or .png.

Use a lowercase file name with hyphens, for example your-theme-name-preview.jpg. Spaces and capital letters can cause path problems on some servers.

Step 2: Put the image in the assets folder

Place the image in this folder of your plugin:

YourPluginFolder/
└── src/
    └── Resources/
        └── app/
            └── storefront/
                └── src/
                    └── assets/
                        └── your-theme-name-preview.jpg

The full path from the plugin root is src/Resources/app/storefront/src/assets/your-theme-name-preview.jpg.

Important: do not put the image in the config folder or directly in the storefront folder. src/assets/ is the location that is reliably included when you package the plugin as a ZIP.

Step 3: Set previewMedia in theme.json

Open src/Resources/theme.json and add previewMedia. A minimal file with the preview configured looks like this:

{
  "name": "YourThemeName",
  "author": "Your Name or Company",
  "description": {
    "en-GB": "A custom Shopware storefront theme.",
    "de-DE": "Ein benutzerdefiniertes Shopware Storefront-Theme."
  },
  "previewMedia": "app/storefront/src/assets/your-theme-name-preview.jpg",
  "style": ["@Storefront"],
  "script": ["@Storefront"],
  "asset": []
}

The previewMedia path is relative to the Resources folder, so it starts with app/storefront/src/assets/ – not with src/Resources/.

Step 4: Clear the cache and check

Clear the cache in the Administration under Settings > System > Caches & indexes, or run php bin/console cache:clear if you have shell access.

Then open Sales Channels > Themes. Your theme should now show the preview image.

If you deliver the theme to clients or publish it in the Shopware Store, the assets folder must be in the ZIP. A common mistake is a build script or archive rule that leaves it out.

Check your .gitignore, build tool or CI pipeline. A correct plugin ZIP contains at least:

• composer.json
• src/YourThemePlugin.php (the plugin bootstrap file)
• src/Resources/theme.json
• src/Resources/app/storefront/src/assets/your-theme-name-preview.jpg

No preview after installation

• Check the file: the image must exist in src/Resources/app/storefront/src/assets/.
• Check the path in theme.json: previewMedia must not start with src/Resources/ – it starts with app/storefront/src/assets/.
• Clear all caches: Shopware caches theme data. Clear the application cache and any HTTP cache.
• Reinstall the plugin: deactivating and reinstalling the theme plugin makes Shopware read the theme configuration again.

Preview missing after a ZIP upload

If the preview works locally but not after uploading the ZIP, the assets folder is almost certainly missing from the archive. Build the ZIP again, check its contents and upload it again.

Image looks distorted or cropped

Shopware does not enforce exact dimensions, but very small or narrow images can look distorted in the gallery. Use a landscape image at least 800 pixels wide.

Put the image in src/Resources/app/storefront/src/assets/, point previewMedia in theme.json to app/storefront/src/assets/…, clear the cache and check that the assets folder is in your ZIP. That is all it takes.

Want to see themes and plugins we have published? Browse our Shopware extensions. Agencies can hand theme and plugin work to us under their own brand – see white-label Shopware development for agencies.