Config Schema
Full reference of all theme.json fields shipped by DmfGuppyTheme, grouped by area. Admin access: Content → Themes → Guppy Theme → Configure.
Layout & container
Container widths
| Field | Type | Default | Description |
|---|---|---|---|
guppy-container-width-default | text | 1400px | Default container |
guppy-container-width-fluid | text | 100% | Fluid container |
guppy-container-width-sm | text | 1230px | Small container |
Container padding
| Breakpoint | Field | Default |
|---|---|---|
| XXL | guppy-container-default-padding-x-xxl | 48px |
| XL | guppy-container-default-padding-x-xl | 48px |
| LG | guppy-container-default-padding-x-lg | 48px |
| MD | guppy-container-default-padding-x-md | 48px |
| SM | guppy-container-default-padding-x-sm | 24px |
| Mobile | guppy-container-default-padding-x-mobile | 10px |
General settings
Tab Layout, block General settings:
| Field | Type | Default | Effect |
|---|---|---|---|
guppy-border-radius | text | 4px | Base corner radius of the theme (since 2.9.0) |
guppy-slider-arrows-round | switch | off | Round slider arrows (since 2.9.0) |
guppy-ui-icons-phosphor | switch | off | Phosphor glyphs for form and UI controls (since 2.9.0) |
Border radius (guppy-border-radius): a px value is converted to rem (4px = 0.25rem), a rem value is used as is, and a value without a unit counts as px (0 gives square corners, 8 equals 8px). An empty field or another unit falls back to 0.25rem. The field sets Bootstrap's $border-radius (--bs-border-radius) for cards, the account menu, .btn-close, gallery thumbnails, filter elements and the other components that use the base radius. The small, large and extra-large radii are derived from it with fixed ratios (×0.6, ×1.5, ×3, ×6), so footer logos and slider arrows follow it too. With the default 4px the output is the same as before 2.9.0. Inputs and buttons keep Input & Button border radius (sw-input-btn-border-radius), product boxes keep the radius of the Guppy Cards tab (guppy-cards-border-radius).
Round slider arrows (guppy-slider-arrows-round): when on, the previous/next and play/pause buttons of the image slider, image gallery and Splide slider elements are circles, regardless of the border radius. Product and cross-selling sliders keep their arrows. When off, the arrows keep the base radius × 2 (rounded squares).
Phosphor icons for form and UI controls (guppy-ui-icons-phosphor): when on, the close button X, the select arrow, the checkbox tick, the accordion arrow and the validation icons of form fields use Phosphor glyphs in the bold weight instead of Bootstrap's glyphs. Colours, sizes and positions stay. Guppy hides the validation icons, so these two only show in a child theme that enables them. Radio dot, indeterminate checkbox, switch knob and the dark colour mode keep Bootstrap's glyphs. The SCSS variables behind it are listed under Theme Variables → Icons.
CMS section padding
Adds extra padding controls to Shopping Experience sections, directly in the section settings modal:
| Field | Type | Default | Description |
|---|---|---|---|
guppy-cms-section-padding-x | text | 48px | Horizontal padding |
guppy-cms-section-padding-y | text | 48px | Default vertical padding |
guppy-cms-section-padding-y-2x | text | 96px | Extra vertical padding (2x) |
Section options in the editor:
| Option | Effect |
|---|---|
| Horizontal padding | Toggle |
| Padding top & bottom | Default Y padding |
| Extra Large (2x) | Double Y padding |
| Padding top | Top only (with No spacing option) |
| Padding bottom | Bottom only (with No spacing option) |
Customise in a child theme:
$guppy-cms-section-padding-x: 32px;
$guppy-cms-section-padding-y: 64px;
$guppy-cms-section-padding-y-2x: 128px;Header
Header variant
| Field | Type | Options | Default |
|---|---|---|---|
guppy-header | select | default, compact, extended, simple | extended |
| Variant | Description |
|---|---|
default | Shopware default header |
compact | Guppy default, compact |
extended | With top bar |
simple | Minimalist |
Header options
| Field | Type | Default | Effect |
|---|---|---|---|
guppy-header-max-height | text | 22px | Max logo height |
guppy-topbar-background-color | color | #EEEEEE | Top bar background colour |
guppy-header-skip-to-main-content | bool | false | Skip link to main content |
guppy-header-skip-to-main-nav | bool | false | Skip link to navigation |
guppy-header-skip-to-search | bool | false | Skip link to search |
Skip links default to on in 3.0.0
Guppy 3.0.0 changes the default of the three skip link fields to true, so the storefront renders skip links with default config, as Shopware core does. Until then the default config renders none. To keep them off after 3.0.0, store false for the three fields now. The theme manager only saves values that changed since the page was loaded, so switch each field on, save, switch it off and save again.
Footer
Footer variant
| Field | Type | Options | Default |
|---|---|---|---|
guppy-footer | select | default, guppy-default | guppy-default |
Footer configuration
| Field | Type | Default | Effect |
|---|---|---|---|
guppy-footer-border-top-color | text | default-border | Top border color |
guppy-footer-show-payment-methods | bool | false | Show payment methods |
guppy-footer-show-shipping-methods | bool | false | Show shipping methods |
Custom fields for shipping / payment methods
DmfGuppyTheme registers the custom field set guppy_footer_options:
| Field | Type | Effect |
|---|---|---|
guppy_hide_in_footer | bool | If active: don't render the method in the footer |
guppy_alternative_label | text | Overrides the tooltip name on hover |
Social media links
As of 2.7.12 no longer theme configuration, but the custom field set guppy_social_media_links on the sales_channel entity, which makes the links per sales channel and per language. Every field is of type text and expects the full URL.
| Field | Platform |
|---|---|
guppy_social_media_instagram_threads | Instagram Threads |
guppy_social_media_instagram | |
guppy_social_media_linkedin | |
guppy_social_media_youtube | YouTube |
guppy_social_media_x | X (Twitter) |
guppy_social_media_facebook | |
guppy_social_media_tiktok | TikTok |
guppy_social_media_xing |
The former guppy-footer-social-media-* theme fields were removed from theme.json in 2.8.0. For the move and its migration see Footer → Social media links.
Custom section images (1–4)
| Field | Type |
|---|---|
guppy-footer-custom-section-image-1 | media |
guppy-footer-custom-section-image-1-link | text |
guppy-footer-custom-section-image-2 | media |
guppy-footer-custom-section-image-2-link | text |
| (up to image 4) | … |
USP banner
As of Guppy 2.8.0 the USP banner no longer lives in the theme configuration but in the DmfUspBanner plugin. The guppy-usp-* settings are gone, and a migration clears their values from the theme configuration.
The banner is maintained in the administration under Content → USP banner, per sales channel and per language. The top bar background colour stays in the theme and is now called guppy-topbar-background-color.
Product cards
| Field | Type | Options | Default |
|---|---|---|---|
guppy-productcard-config | select | default, guppy-default | guppy-default |
guppy-productcard-protective-frame | bool | – | true |
guppy-productcard-image-object-fit | select | contain, cover | contain |
Product detail
Buybox
| Field | Type | Default | Effect |
|---|---|---|---|
guppy-detail-buybox-styling | select | default | default, border, background |
guppy-detail-headline-buybox | bool | true | Product name in buybox |
guppy-detail-buybox-contact | bool | false | Show contact info |
guppy-detail-buybox-contact-hotline | bool | false | Show hotline |
guppy-detail-buybox-hide-quantity-buttons | bool | false | Hide quantity buttons |
guppy-detail-mobile-title-above-gallery | bool | false | Product title above gallery on mobile |
Gallery & tabs
| Field | Type | Default | Effect |
|---|---|---|---|
guppy-detail-gallery-scroll | bool | false | Gallery scrolls with content |
guppy-detail-display-properties-as-tab | bool | false | Properties as a separate tab |
Login & register
| Field | Type | Options | Default |
|---|---|---|---|
guppy-login-register | select | default, compact | compact |
Deprecated since 2.9.0
guppy-login-register and its tab Login & Register have no effect since 2.7.0: the login and register pages render Shopware's templates whatever the field holds. Since 2.9.0 label and help text say so ("no effect since 2.7.0, removed in 3.0.0"). Guppy 3.0.0 removes the field and the tab, and a migration removes the stored value. Remove theme_config('guppy-login-register') from child theme templates and the field from a child theme's theme.json before then.
The checkout field guppy-checkout was removed in 2.7.0. Since 2.9.0 the migration Migration1792627200RemoveRetiredCheckoutThemeConfigKey also removes its stored value, which some shops still showed as a loose field under "General" in the theme manager. It runs with bin/console plugin:update DmfGuppyTheme.
Badges
Basics
| Field | Type | Default |
|---|---|---|
guppy-badges-show-outline | bool | false |
New badge
| Field | Type | Default |
|---|---|---|
guppy-badges-new-background-color | color | #22C087 |
guppy-badges-new-color | color | #FFFFFF |
guppy-badges-new-outline-color | color | #FFFFFF |
Top-seller badge
| Field | Type | Default |
|---|---|---|
guppy-badges-top-seller-background-color | color | #F89C00 |
guppy-badges-top-seller-color | color | #FFFFFF |
guppy-badges-top-seller-outline-color | color | #FFFFFF |
Discount badge
| Field | Type | Default |
|---|---|---|
guppy-badges-discount-background-color | color | #E10036 |
guppy-badges-discount-color | color | #FFFFFF |
guppy-badges-discount-outline-color | color | #FFFFFF |
Out-of-stock badge
| Field | Type | Default |
|---|---|---|
guppy-badges-show-out-of-stock | bool | false |
guppy-badges-out-of-stock-background-color | color | #EEEEEE |
guppy-badges-out-of-stock-color | color | #303030 |
guppy-badges-out-of-stock-outline-color | color | #303030 |
A product counts as out of stock when its "Closeout" option is enabled and its stock has dropped below the minimum purchase quantity.
When the out-of-stock badge is shown on a product card (because the product is out of stock), it replaces the other badges (new, top-seller, discount) on that card. Products that are not out of stock are unaffected.
Alerts
Colors
| Field | Type | Default | Effect |
|---|---|---|---|
guppy-alert-color-success | color | #D3F2E7 | Success background |
guppy-alert-color-success-text | select | dark | Success text color |
guppy-alert-color-info | color | #CEEDFE | Info background |
guppy-alert-color-info-text | select | dark | Info text color |
guppy-alert-color-warning | color | #FFEFD4 | Warning background |
guppy-alert-color-warning-text | select | dark | Warning text color |
guppy-alert-color-danger | color | #FDE2E7 | Danger background |
guppy-alert-color-danger-text | select | dark | Danger text color |
Options
| Field | Type | Default | Effect |
|---|---|---|---|
guppy-alert-alert-outline-active | bool | false | Outline border on alerts |
Color system
Brand
| Field | Type | Default | Use |
|---|---|---|---|
sw-color-brand-primary | color | #215AFF | Primary |
sw-color-brand-secondary | color | #0B1845 | Secondary |
Greyscales
| Field | Default |
|---|---|
sw-color-gray-100 | #F9F9F9 |
sw-color-gray-200 | #EEEEEE |
sw-color-gray-300 | #BCC1C7 |
sw-color-gray-400 | #CED4DA |
sw-color-gray-500 | #ADB5BD |
sw-color-gray-600 | #798490 |
sw-color-gray-700 | #495057 |
sw-color-gray-800 | #4A545B |
sw-color-gray-900 | #212529 |
Focus and form field border
Block Theme colours, both empty by default:
| Field | Type | Empty means | Effect |
|---|---|---|---|
guppy-focus-color | color | primary colour (sw-color-brand-primary) | Keyboard focus indicator (since 2.9.0) |
guppy-input-border-color | color | border colour (sw-border-color) | Border of form fields and dropdown menus (since 2.9.0) |
Focus colour (guppy-focus-color): colours the focus outline of Guppy's focus-style() mixin and of buttons, Bootstrap's focus ring (:focus-visible, .form-select, .form-check-input, .nav-link, .pagination, .btn-close), the focus shadow of form fields and buttons and the focus border of form fields, including the header search field. Use it when the primary colour is too light: the focus indicator needs at least 3:1 contrast against adjacent colours (WCAG 1.4.11). The focus shadows of the form validation states keep their success and danger colours.
Form field border (guppy-input-border-color): colours the borders of input fields, selects, checkboxes and radios and dropdown menus (.form-control, .form-select, .form-check-input, .dropdown-menu), and through them the input group addon, the header search buttons, the filter panel toggles and the dropdown dividers, also of the dark dropdown. Use it to reach the 3:1 contrast against the background that WCAG 1.4.11 requires for form controls, without changing the general border colour.
With both fields empty the output is the same as before 2.9.0.
Typography
Font sizes
| Field | Type | Default |
|---|---|---|
sw-font-size-base | text | 1rem |
sw-h1-font-size | text | 32px |
sw-h2-font-size | text | 24px |
sw-h3-font-size | text | 20px |
sw-h4-font-size | text | 18px |
sw-h5-font-size | text | 16px |
sw-h6-font-size | text | 15px |
Line heights
| Field | Default |
|---|---|
sw-h1-line-height | 44px |
sw-h2-line-height | 36px |
sw-h3-line-height | 32px |
sw-h4-line-height | 28px |
sw-h5-line-height | 24px |
sw-h6-line-height | 21px |
Visual change in 2.9.0: h6 line height
Before 2.9.0 sw-h6-line-height had no effect, and h6 / .h6 kept Bootstrap's line height of 1.2 (18px). Since 2.9.0 the field applies like the h1 to h5 fields: with the default 21px the line height is 21px from 1200px up and scales fluidly below (about 20.4px at 375px). This shows in the review area of the product detail page and in the "Delete account" dialog of the profile page (only when account deletion is enabled). To keep the old height, set the field to 1.2 × Heading 6 font size (18px with the default 15px). A value stored in the field before now takes effect. The text-only payment and shipping logos in the footer use the same value and change from 21px to 18px.
Secondary text colour
| Field | Type | Default | Effect |
|---|---|---|---|
guppy-text-secondary-color | color | empty | Colour of muted text (since 2.9.0) |
Secondary text colour sets Bootstrap's $body-secondary-color (--bs-secondary-color): .text-muted, .text-body-secondary, form help texts (.form-text), figure and table captions, the divider and current item of the breadcrumb, disabled nav links, list group action and disabled items, the toast header and the disabled range thumb. Empty falls back to Text colour (sw-text-color), so the output stays the same. The dark colour mode keeps its own value. Body-size text needs at least 4.5:1 contrast against the background (WCAG 1.4.3).
Buttons & inputs
| Field | Type | Default | Effect |
|---|---|---|---|
sw-input-btn-font-size | text | 16px | Button font size |
sw-input-btn-border-radius | text | 4px | Button corner radius |
sw-input-btn-font-weight | select | normal | Button font weight |
Usage in code
In Twig
{% if theme_config('guppy-header') == 'extended' %}
{# Extended header logic #}
{% endif %}In SCSS
Theme values are exposed as CSS custom properties:
.custom-component {
background-color: var(--sw-color-brand-primary);
font-size: var(--sw-font-size-base);
}Related
- Theme Variables: SCSS counterpart of the configuration fields.
- Twig Blocks: override paths in templates.
- Twig Overrides: using fields in your own templates.
- Variables & Tokens: SCSS architecture and mixins.