---
title: Theme Settings | Shopware Community Hub
description: >-
Learn how to configure and manage theme settings in Shopware, including custom
fields, SCSS variables, and theme compilation.
canonical_url: 'https://hub.shopware.com/learn/unit/theme-settings'
---
# Theme Settings
- Understand the basic structure of a theme configuration.
- Know where to add theme settings.
# Theme Settings
In this learning unit, you will learn how to adjust your theme using **configurations**, enhancing its flexibility and adaptability for various scenarios.
## Real-World Example
Imagine you are developing a theme that has a thought through design. You want to allow the user to change the color of the main navigation.
To achieve this, you need to add a configuration field to your theme that allows the user to select a color for the main navigation, for example.
## Checkout Git Tag
To follow along with this learning unit, please checkout the git tag `LU-02-theme-configurations` or continue manually. Beginners are advised to follow the code examples and later checkout the git tag to see the final result.
```shell
cd custom/plugins/AcademyTheme
git checkout LU-02-theme-configurations
```
If you haven't cloned the **AcademyTheme** yet, please do so first and remember to install and activate it:
```bash
cd custom/plugins
git clone https://github.com/ShopwareAcademy/AcademyTheme.git
# Go back to your shop root
cd ../..
bin/console plugin:refresh
bin/console plugin:install AcademyTheme --activate
cd custom/plugins/AcademyTheme
git checkout LU-02-theme-configurations
```
## Change the Theme
Per default, the `Shopware default theme` is assigned to all sales channels. If your theme is not assigned to a sales channel, you can do this in the administration or via a Shopware console command.
Since we are lazy, we simply apply it to all sales channels with the following command:
```shell
bin/console theme:change AcademyTheme --all
```
But you can also assign it to a specific sales channel.
```shell
bin/console theme:change AcademyTheme
```
Then follow the prompt to select the sales channel.
## The `theme.json` File
We already created a `theme.json` file in the previous unit so let's take a closer look at it and the folder structure:
```txt
└── themes
└── AcademyTheme
├── src
│ ├── Resources
│ │ └── theme.json
│ └── AcademyTheme.php
└── composer.json
```
The basic `theme.json` looks like this:
``` json
{
"name": "AcademyTheme",
"author": "Shopware AG",
"description": {
"en-GB": "My custom theme",
},
"views": [
"@Storefront",
"@Plugins",
"@AcademyTheme"
],
"previewMedia": "app/storefront/dist/assets/defaultThemePreview.jpg",
"style": [
"app/storefront/src/scss/overrides.scss",
"@Storefront",
"app/storefront/src/scss/base.scss"
],
"script": [
"@Storefront",
"app/storefront/dist/storefront/js/swag-basic-example-theme.js"
],
"asset": [
"@Storefront",
"app/storefront/src/assets"
],
"configInheritance": [
"@Storefront",
"@OtherTheme"
]
}
```
The `theme.json` mostly consists of metadata about the theme, like the name, author, description, and preview image.
The `views` array defines the order in which the theme's views (Twig files) are loaded. The `style` and `script` arrays define the order in which the theme's styles (SCSS) and scripts (JavaScript) are loaded.
The `asset` array helps you organize your **images** and other static files you might need. The `configInheritance` array defines the order in which the theme's configuration is inherited, since you can override configs from other themes.
The last entry has the highest priority. For example, in the `views` section, this is important when your shop uses many plugins, because the order determines which Twig template overrides another.
For an in depth explanation of the `theme.json` file, please refer to the [official documentation](https://developer.shopware.com/docs/guides/plugins/themes/theme-configuration.html).
## Input Color Field
The color field is a common input field type that allows the user to select a color from a color picker. To add a color field to your theme, you need to add the following code to your `theme.json` file:
```json5
{
//...
"config": {
"fields": {
"academy-color-status-neutral": {
"label": {
"en-GB": "Neutral status colour",
"de-DE": "Neutrale Status Farbe"
},
"type": "color",
"value": "#999999",
"editable": true,
"tab": "colours",
"block": "themeColours",
"section": "importantColours"
}
}
}
}
```
Shopware themes automatically inherit configuration fields from their parent themes. This means that even if your own theme defines only a single color field (such as `academy-color-status-neutral`), you may still see additional fields such as primary, secondary, and others in the theme configuration.
These inherited fields come from the core theme configuration located at `vendor/shopware/storefront/theme.json`
Great, we can now check in our SCSS code for this value and apply it to the main navigation.
## Using the Color in SCSS
To use the colors in your SCSS code, you simply use them as variables. They are injected during theme compilation. Here is an example of how to use the color in your SCSS code:
```scss
.navigation {
background-color: $academy-color-status-neutral;
}
```
Place your custom SCSS rules inside your **`base.scss`** file.
## Managing the Settings View
If you have more than a few configuration fields (4), you might want to group them and add tabs for a better overview.
This can be done with sections (3), blocks (2), and tabs (1).
Here is an example of how to group the color field in a section:
```json
{
"name": "Just another theme",
"author": "Just another author",
"config": {
"blocks": {
"themeColours": {
"label": {
"en-GB": "Theme colours",
"de-DE": "Theme Farben"
}
}
},
"sections": {
"importantColours": {
"label": {
"en-GB": "Important colours",
"de-DE": "Wichtige Farben"
}
}
},
"tabs": {
"colours": {
"label": {
"en-GB": "Colours",
"de-DE": "Farben"
}
}
},
"fields": {
"academy-color-status-neutral": {
"label": {
"en-GB": "Neutral status colour",
"de-DE": "Neutrale Status Farbe"
},
"type": "color",
"value": "#999999",
"editable": true,
"tab": "colours",
"block": "themeColours",
"section": "importantColours"
}
}
}
}
```
## Shopware Console Commands
You do need to `compile` the theme after you have added the configuration. Compiling a theme in Shopware involves processing the theme's assets (like SCSS and JavaScript files) and generating the final output that will be used in the storefront. This process ensures that all changes made to the theme's configuration and assets are applied and visible in the shop.
This can be done with the Shopware console command `theme:compile`.
Here is a list of all **theme** related CLI commands:
```bash
Available commands for the "theme" namespace:
theme:change Change the active theme for a sales channel
theme:compile Compile the theme
theme:create Create a new theme
theme:dump Dump the theme configuration
theme:prepare-icons Prepare the theme icons
theme:refresh Refresh the theme configuration
```
## Final Result
Ok, let's see the final result. The field name is used in the SCSS file as a variable. So `academy-color-status-neutral` becomes `$academy-color-status-neutral`.
We are simply using this color in the main navigation background to make it easier to identify.
```scss
.main-navigation {
background-color: $academy-color-status-neutral;
}
```
```shell
bin/console theme:compile
```
After compiling the theme, you should see the color change from **white** to a **light gray** (or color you set yourself in the administration) in the main navigation:
1. Ensure that your theme is installed and activated before you run the **`bin/console theme:compile`** command.
2. Keep in mind that you may need to run the **`bin/console cache:clear`** command after you have added new configuration fields.
3. You can also use the **`bin/console theme:refresh`** command to refresh the theme configuration.
4. You can also use the **`bin/console theme:dump`** command to see the theme configuration under `[shop_root]/var/theme-files.json`.
## Summary
In this learning unit, you learned how to:
- Assign and activate your custom theme for one or all sales channels.
- Understand the structure and purpose of the **`theme.json`** file.
- Add custom configuration fields (e.g., color pickers) to your theme.
- Use those configuration values as SCSS variables in your styling.
- Organize settings with **tabs**, **sections**, and **blocks** for better usability.
- Compile and refresh your theme.
With this knowledge, you can now create configurable themes that give shop owners and managers more control over the look and feel of their shop.