Theme configuration

Overview

This guide shows you how the theme configuration works and explains the possibilities of the settings in more depth.

Prerequisites

This guide is built upon the guide on creating a first theme:

Structure of theme configuration

The theme configuration for a theme is located in the theme.json file <plugin root>/src/Resources folder. Open up the <plugin root>/src/Rescoure/theme.json file with your favorite code-editor. The configuration looks like this.
<plugin root>/src/Resources/theme.json
1
{
2
"name": "SwagBasicExampleTheme",
3
"author": "Shopware AG",
4
"views": [
5
"@Storefront",
6
"@Plugins",
7
"@SwagBasicExampleTheme"
8
],
9
"style": [
10
"app/storefront/src/scss/overrides.scss",
11
"@Storefront",
12
"app/storefront/src/scss/base.scss"
13
],
14
"script": [
15
"@Storefront",
16
"app/storefront/dist/storefront/js/swag-basic-example-theme.js"
17
],
18
"asset": [
19
"@Storefront",
20
"app/storefront/src/assets"
21
]
22
}
Copied!
If you make changes or additions to the theme.json file, you must then execute the theme:refresh command to put them into effect. Run bin/console theme:refresh in order to update your theme.
Let's have a closer look at each section.
<plugin root>/src/Resources/theme.json
1
{
2
"name": "SwagBasicExampleTheme",
3
"author": "Shopware AG",
4
"description": {
5
"en-GB": "Just another description",
6
"de-DE": "Nur eine weitere Beschreibung"
7
},
8
...
9
}
Copied!
Here change the name of your theme and the author. The description section is optional and as you notice it is also translatable.
The views section controls the template inheritance. This will be covered in the Theme inheritance guide.
<plugin root>/src/Resources/theme.json
1
{
2
...
3
"views": [
4
"@Storefront",
5
"@Plugins",
6
"@SwagBasicExampleTheme"
7
],
8
...
9
}
Copied!
The style section determines the order of the CSS compilation. In the <plugin root>/app/storefront/src/scss/base.scss file you can apply your changes you want to make to the @Storefront standard styles or add other styles you need. The <plugin root>/app/storefront/src/scss/overrides.scss file is used for a special case. Maybe you need to override some defined variables or functions defined by Shopware or Boostrap, you can implement your changes here. Checkout the Override bootstrap variables in a theme guide for further information.
<plugin root>/src/Resources/theme.json
1
{
2
...
3
"style": [
4
"app/storefront/src/scss/overrides.scss",
5
"@Storefront",
6
"app/storefront/src/scss/base.scss"
7
],
8
...
9
}
Copied!

Assets

The asset option you can configure your paths to your assets like images, fonts, etc. The standard location to put your assets to is the <plugin root>/app/storefront/src/assets folder. Checkout the Add assets to theme guide for further information.
<plugin root>/src/Resources/theme.json
1
{
2
...
3
"asset": [
4
"app/storefront/src/assets"
5
]
6
...
7
}
Copied!
If you need the assets from the default storefront theme for your custom theme, just add @Storefront as asset path
<plugin root>/src/Resources/theme.json
1
{
2
...
3
"asset": [
4
"@Storefront",
5
"app/storefront/src/assets"
6
]
7
...
8
}
Copied!

Config fields

One of the benefits of creating a theme is that you can overwrite the theme configuration of the default theme or add your own configurations.
<plugin root>/src/Resources/theme.json
1
{
2
...
3
"asset":[
4
...
5
],
6
"config": {
7
"fields": {
8
"sw-color-brand-primary": {
9
"value": "#00ff00"
10
}
11
}
12
}
13
}
Copied!
In the example above, we change the primary color to green. You always inherit from the storefront config and both configurations are merged. This also means that you only have to provide the values you actually want to change. You can find a more detailed explanation of the configuration inheritance in the section Theme inheritance.
If you overwrite variables of another theme from a third party provider and these are renamed or removed at a later time, this can lead to issues and the theme can no longer be compiled. So be aware of it.
The theme.json contains a config property which contains a list of tabs, blocks, sections and fields.
The key of each config field item is also the technical name which you use to access the config option in your theme or scss files. config entries will show up in the administration and can be customized by the end user (if editable is set to true, see table below).
The following parameters can be defined for a config field item:
Name
Meaning
label
Array of translations with locale code as key
type
Type of the config. Possible values: color, text, number, fontFamily, media, checkbox, switch and url
editable
If set to false, the config option will not be displayed (e.g. in the administration)
tab
Name of a tab to organize the config options
block
Name of a block to organize the config options
section
Name of a section to organize the config options
custom
The defined data will not be processed but is available via API
scss
If set to false, the config option will not be injected as a SCSS variable
fullWidth
If set to true, the administration component width will be displayed in full width

Field types

You can use different field types in your theme manager:
A text field example:
<plugin root>/src/Resources/theme.json
1
{
2
...
3
"config": {
4
"fields": {
5
"modal-padding": {
6
"label": {
7
"en-GB": "Modal padding",
8
"de-DE": "Modal Innenabstand"
9
},
10
"type": "text",
11
"value": "(0, 0, 0, 0)",
12
"editable": true
13
}
14
}
15
}
16
}
Copied!
A number field example:
<plugin root>/src/Resources/theme.json
1
{
2
...
3
"config": {
4
"fields": {
5
"visible-slides": {
6
"label": {
7
"en-GB": "Number of visible slides",
8
"de-DE": "Anzahl an sichtbaren Slider Bildern"
9
},
10
"type": "number",
11
"custom": {
12
"numberType": "int",
13
"min": 1,
14
"max": 6
15
},
16
"value": 3,
17
"editable": true
18
}
19
}
20
}
21
}
Copied!
Two boolean field examples:
<plugin root>/src/Resources/theme.json
1
{
2
...
3
"config": {
4
"fields": {
5
"navigation-fixed": {
6
"label": {
7
"en-GB": "Fix navigation",
8
"de-DE": "Navigation fixieren"
9
},
10
"type": "switch",
11
"value": true,
12
"editable": true
13
}
14
}
15
}
16
}
Copied!
or
<plugin root>/src/Resources/theme.json
1
{
2
...
3
"config": {
4
"fields": {
5
"navigation-fixed": {
6
"label": {
7
"en-GB": "Fix navigation",
8
"de-DE": "Navigation fixieren"
9
},
10
"type": "checkbox",
11
"value": true,
12
"editable": true
13
}
14
}
15
}
16
}
Copied!

Examples for custom config fields

A custom single-select field example
<plugin root>/src/Resources/theme.json
1
{
2
"name": "Just another theme",
3
"author": "Just another author",
4
"description": {
5
"en-GB": "Just another description",
6
"de-DE": "Nur eine weitere Beschreibung"
7
},
8
"views": [
9
"@Storefront",
10
"@Plugins",
11
"@SelectExample"
12
],
13
"style": [
14
"app/storefront/src/scss/overrides.scss",
15
"@Storefront",
16
"app/storefront/src/scss/base.scss"
17
],
18
"script": [
19
"@Storefront",
20
"app/storefront/dist/storefront/js/select-example.js"
21
],
22
"asset": [
23
"@Storefront",
24
"app/storefront/src/assets"
25
],
26
"config": {
27
"blocks": {
28
"exampleBlock": {
29
"label": {
30
"en-GB": "Example block",
31
"de-DE": "Beispiel Block"
32
}
33
}
34
},
35
"sections": {
36
"exampleSection": {
37
"label": {
38
"en-GB": "Example section",
39
"de-DE": "Beispiel Sektion"
40
}
41
}
42
},
43
"fields": {
44
"my-single-select-field": {
45
"label": {
46
"en-GB": "Select a font size",
47
"de-DE": "Wähle ein Schriftgröße"
48
},
49
"type": "text",
50
"value": "24",
51
"custom": {
52
"componentName": "sw-single-select",
53
"options": [
54
{
55
"value": "16",
56
"label": {
57
"en-GB": "16px",
58
"de-DE": "16px"
59
}
60
},
61
{
62
"value": "20",
63
"label": {
64
"en-GB": "20px",
65
"de-DE": "20px"
66
}
67
},
68
{
69
"value": "24",
70
"label": {
71
"en-GB": "24px",
72
"de-DE": "24px"
73
}
74
}
75
]
76
},
77
"editable": true,
78
"block": "exampleBlock",
79
"section": "exampleSection"
80
}
81
}
82
}
83
}
Copied!
Example of a custom single-select field
A custom multi-select field example
<plugin root>/src/Resources/theme.json
1
{
2
"name": "Just another theme",
3
"author": "Just another author",
4
"description": {
5
"en-GB": "Just another description",
6
"de-DE": "Nur eine weitere Beschreibung"
7
},
8
"views": [
9
"@Storefront",
10
"@Plugins",
11
"@SelectExample"
12
],
13
"style": [
14
"app/storefront/src/scss/overrides.scss",
15
"@Storefront",
16
"app/storefront/src/scss/base.scss"
17
],
18
"script": [
19
"@Storefront",
20
"app/storefront/dist/storefront/js/select-example.js"
21
],
22
"asset": [
23
"@Storefront",
24
"app/storefront/src/assets"
25
],
26
"config": {
27
"blocks": {
28
"exampleBlock": {
29
"label": {
30
"en-GB": "Example block",
31
"de-DE": "Beispiel Block"
32
}
33
}
34
},
35
"sections": {
36
"exampleSection": {
37
"label": {
38
"en-GB": "Example section",
39
"de-DE": "Beispiel Sektion"
40
}
41
}
42
},
43
"fields": {
44
"my-multi-select-field": {
45
"label": {
46
"en-GB": "Select some colours",
47
"de-DE": "Wähle Farben aus"
48
},
49
"type": "text",
50
"editable": true,
51
"value": [
52
"green",
53
"blue"
54
],
55
"custom": {
56
"componentName": "sw-multi-select",
57
"options": [
58
{
59
"value": "green",
60
"label": {
61
"en-GB": "green",
62
"de-DE": "grün"
63
}
64
},
65
{
66
"value": "red",
67
"label": {
68
"en-GB": "red",
69
"de-DE": "rot"
70
}
71
},
72
{
73
"value": "blue",
74
"label": {
75
"en-GB": "blue",
76
"de-DE": "blau"
77
}
78
},
79
{
80
"value": "yellow",
81
"label": {
82
"en-GB": "yellow",
83
"de-DE": "gelb"
84
}
85
}
86
]
87
},
88
"block": "exampleBlock",
89
"section": "exampleSection"
90
}
91
}
92
}
93
}
Copied!
Example of a custom multi-select field

Tabs, blocks and sections

You can use tabs, blocks and sections to structure and group the config options.
Example of tabs, blocks and sections
In the picture above are four tabs. In the "Colours" tab there is one block "Theme colours" which contains two sections named "Important colors" and "Other". You can define the block and section individually for each item. Example:
<plugin root>/src/Resources/theme.json
1
{
2
"name": "Just another theme",
3
"author": "Just another author",
4
5
"config": {
6
"fields": {
7
"sw-color-brand-primary": {
8
"label": {
9
"en-GB": "Primary colour",
10
"de-DE": "Primär"
11
},
12
"type": "color",
13
"value": "#399",
14
"editable": true,
15
"tab": "colors",
16
"block": "themeColors",
17
"section": "importantColors"
18
}
19
}
20
}
21
}
Copied!
The tab and section property is not required.
You can extend the config to add translated labels for the tabs, blocks and sections:
<plugin root>/src/Resources/theme.json
1
{
2
"name": "Just another theme",
3
"author": "Just another author",
4
5
"config": {
6
"blocks": {
7
"colors": {
8
"themeColors": {
9
"en-GB": "Theme colours",
10
"de-DE": "Theme Farben"
11
}
12
}
13
},
14
"sections": {
15
"importantColors": {
16
"label": {
17
"en-GB": "Important colors",
18
"de-DE": "Wichtige Farben"
19
}
20
}
21
},
22
"tabs": {
23
"colors": {
24
"label": {
25
"en-GB": "Colours",
26
"de-DE": "Farben"
27
}
28
}
29
},
30
"fields": {
31
"sw-color-brand-primary": {
32
"label": {
33
"en-GB": "Primary colour",
34
"de-DE": "Primär"
35
},
36
"type": "color",
37
"value": "#399",
38
"editable": true,
39
"tab": "colors",
40
"block": "themeColors",
41
"section": "importantColors"
42
}
43
}
44
}
45
}
Copied!

Next steps

Now that you know how to configure your theme, here is a list of things you can do.
Last modified 2mo ago