Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 30 ยท Storefront

Styling and JavaScript in the Storefront

Style and script the Shopware 6 storefront: theme.json, SCSS variable overrides, JavaScript plugins bound to data attributes, build commands and accessibility.

Twig gives the storefront its markup. Two more layers make it look and behave right: SCSS for styling and JavaScript plugins for behavior. Shopware builds both for you from files in your plugin or theme, combines them with the core storefront code and serves the result as a few compiled files. What you need to learn is where to put your files, in which order they are loaded, and how the storefront's own small plugin system attaches your JavaScript to the right elements.

This lesson covers theme.json, SCSS variable overrides, the JavaScript plugin base class and data attributes, the build and compile commands, and basic accessibility habits. Real configuration, SCSS, JavaScript and commands are read-only, because Shopware cannot run on this site. The runnable examples are stand-ins: a PHP model of how SCSS variables and !default interact, and a browser demo of a plugin registry that binds classes to data attributes. They are not the real build, and each one says what is simplified. The markup you style usually comes from Storefront Templates with Twig.

Plugin or theme?

A plugin can add SCSS and JavaScript to the storefront, but it applies to whatever theme is active. A theme is a special kind of extension that also owns the look of a sales channel: it declares the stylesheets, scripts, assets and merchant-editable settings in a theme.json file. Use a plugin for a feature (a badge, a store locator), and a theme for a brand design. Many projects use both: a theme for the look, plugins for features.

theme.json

A theme's theme.json (read-only) lists what the build must include and in which order:

JSON
{
  "name": "AcmeTheme",
  "author": "Acme GmbH",
  "views": ["@Storefront", "@Plugins", "@AcmeTheme"],
  "style": [
    "app/storefront/src/scss/overrides.scss",
    "@StorefrontBootstrap",
    "@Storefront",
    "app/storefront/src/scss/base.scss"
  ],
  "script": [
    "@Storefront",
    "app/storefront/dist/storefront/js/acme-theme/acme-theme.js"
  ],
  "asset": [
    "@Storefront",
    "app/storefront/src/assets"
  ],
  "config": {
    "fields": {
      "acme-badge-color": {
        "label": { "en-GB": "Badge color", "de-DE": "Badge-Farbe" },
        "type": "color",
        "value": "#c0392b",
        "editable": true,
        "block": "colors"
      }
    }
  }
}

The keys that matter:

  • views is the template lookup order. Later entries win, so your theme's templates override the core and plugin templates.
  • style is the list of SCSS entry points, in order. Your overrides.scss comes first, so the variables you set there are already defined when Bootstrap and the storefront declare their defaults. Your base.scss comes last, so its rules can override core rules.
  • script lists JavaScript bundles; asset lists folders of images and fonts.
  • config defines settings that a merchant can change in the Administration without touching code. Each field becomes an SCSS variable (here $acme-badge-color) and can be used in your styles. Check the skeleton of your Shopware version for the exact sections and field types.

A plain plugin has no theme.json. It just places a base.scss at Resources/app/storefront/src/scss/base.scss and a main.js at Resources/app/storefront/src/main.js, which the build picks up on its own.

SCSS variables and the !default flag

Bootstrap and the storefront define their variables with the !default flag, which means "set this only if nobody has set it before". That one flag is why overriding works:

SCSS
// overrides.scss, loaded BEFORE Bootstrap and the storefront
$primary: #c0392b;
$border-radius: 0.125rem;
SCSS
// inside Bootstrap, loaded AFTER your overrides
$primary: #0d6efd !default;       // ignored, you already set it
$btn-bg: $primary !default;       // computed from YOUR primary

Because many values are derived from others ($btn-bg from $primary), the position of your assignment matters. If you assign $primary after Bootstrap has already computed its derived values, the derived ones keep the old color. This is the number one source of "my color change only applies in some places". Put variable overrides in overrides.scss, put new rules in base.scss.

flowchart LR
    A["Theme config values<br/>(Administration)"] --> B["overrides.scss<br/>your variables"]
    B --> C["Bootstrap and Storefront<br/>variables with !default"]
    C --> D["Core storefront rules"]
    D --> E["base.scss<br/>your rules"]
    E --> F["Compiled all.css"]

Variables flow from your overrides into the defaults; your own rules come last so they win over the core.

A !default stand-in

This first stand-in walks through SCSS-like files in order and applies the !default rule. It is real in the rule (set once, derived values use the value at that moment) and simplified in everything else: it understands only $name: value; lines, !default, and $name references. It is not a Sass compiler.

PHP Why the order of SCSS files matters

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

In scenario 3 the radius changed, but the button background did not: $btn-bg had already been computed from the old $primary. Real Sass behaves the same way, which is why overrides.scss is loaded first.

JavaScript plugins

The storefront does not use a front-end framework. Its behavior is organized into small plugins: classes that attach to elements on the page. A plugin class extends the storefront's Plugin base class (read-only):

JavaScript
import Plugin from 'src/plugin-system/plugin.class';

export default class AcmeBadgePlugin extends Plugin {
    static options = {
        text: 'New',
        dismissible: false,
    };

    init() {
        this._registerEvents();
    }

    _registerEvents() {
        this.el.addEventListener('click', this._onClick.bind(this));
    }

    _onClick() {
        this.el.setAttribute('aria-pressed', 'true');
    }
}

The base class gives you this.el (the DOM element the plugin is bound to) and this.options (your static options merged with the values from the page). init() is called once per element. Register the class in main.js:

JavaScript
import AcmeBadgePlugin from './plugin/acme-badge.plugin';

const PluginManager = window.PluginManager;
PluginManager.register('AcmeBadge', AcmeBadgePlugin, '[data-acme-badge]');

register() takes a name, the class and a CSS selector. When the page has loaded, the plugin manager looks for all elements matching the selector and creates one plugin instance per element. Options come from a data attribute named after the plugin in kebab case, and the template provides it:

TWIG
<span data-acme-badge="true"
      data-acme-badge-options='{ "text": "Limited", "dismissible": true }'>
</span>

A few good habits:

  • Bind to data attributes, not to CSS classes. Classes change with design; data attributes are a stable contract between the template and the script.
  • Use this.el and this.options instead of global selectors. A plugin must work when the same element appears twice on a page.
  • Re-initialize after AJAX. Content loaded later (an off-canvas cart, a filtered list) is new DOM. The manager can initialize plugins on it again, and it skips elements that already have an instance.
  • Clean up. If you add listeners to document or window, remove them again when your element goes away.
  • Keep it small. A plugin for one badge does not need a library.

Building, compiling and hot reload

The sources are not what the browser loads. Commands turn them into compiled files:

Terminal
# build all storefront JavaScript, including your plugin's main.js
bin/build-storefront.sh

# compile the SCSS of the active theme(s) and write the CSS
bin/console theme:compile

# development with live reload
bin/watch-storefront.sh

theme:compile runs the SCSS pipeline (variables, imports, autoprefixing) and creates the final CSS for each theme and sales channel. After you change theme configuration in the Administration, the theme is compiled again as well. The JavaScript build produces a bundle under your plugin's Resources/app/storefront/dist/storefront/js/ folder. Commit that dist folder if you ship the plugin through the Store or Composer, because production servers usually do not run the Node build. Hot reload (the watch script) serves your assets from a development server and refreshes the browser when you save, which is much faster than rebuilding. The URL and port are printed when it starts; the scripts differ a little between versions, so read the ones in your project's bin folder.

If your change does not show up: confirm the plugin is active, run the build, run theme:compile, clear the cache with bin/console cache:clear, and do a hard reload in the browser.

A plugin registry stand-in

The second stand-in runs in your browser. It is a tiny registry that works like the storefront's plugin manager: you register a class with a selector, it finds the elements, merges default options with the JSON from a data attribute, and creates one instance per element. It is real in how the idea works and simplified in that it is about thirty lines instead of the real manager, with no lifecycle hooks and no lazy loading. Press "Add another counter": the new element gets its plugin because initialization runs again, while the existing ones are not initialized twice.

A mini plugin manager with data attributes

Check the console panel: the first call creates two instances, and every later call creates exactly one, because the WeakMap remembers which elements already have a plugin.

Accessibility notes

Custom behavior is where accessibility often breaks, so build these in from the start:

  • Use real controls. A <button> is focusable and works with Enter and Space for free. A clickable <div> does neither.
  • Keep the focus visible. Never remove outlines without a replacement (the demo above uses :focus-visible). Style the focus ring in your SCSS to match the brand instead.
  • Announce changes. Content that updates without a page load needs an aria-live region (a polite role="status" is enough for most messages), and toggles need aria-expanded or aria-pressed that your script keeps up to date.
  • Check contrast. Text needs at least a 4.5:1 contrast ratio against its background; a merchant-editable color field can break that, so choose safe defaults and say so in the field label.
  • Respect motion preferences. Wrap animations in @media (prefers-reduced-motion: no-preference).
  • Do not depend on hover. Touch users and keyboard users never hover.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is overrides.scss listed before the Storefront styles in theme.json?

    Variables declared with !default only apply when unset. Your values must exist first so the defaults, and the values derived from them, pick them up.
  2. 2. How does a storefront JavaScript plugin get connected to elements on the page?

    PluginManager.register() stores the selector, and the manager creates a plugin instance for each element that matches it.
  3. 3. Where do the options of the plugin AcmeBadge normally come from, besides static options?

    The manager merges the plugin's static options with JSON read from a data attribute named after the plugin in kebab case.
  4. 4. What must you do before releasing a plugin through the Store?

    Production servers usually do not run the Node build, so the compiled files in the dist folder must ship with the plugin.

Summary

  • Plugins add SCSS and JS through conventional paths; themes declare everything in theme.json, including the order of style files and merchant-editable settings.
  • !default variables only apply when nothing set them before, so put variable overrides in overrides.scss and rules in base.scss.
  • Storefront JavaScript is organized as plugin classes (Plugin base class, init(), this.el, this.options) registered with a name, class and selector, and configured through data attributes.
  • Use bin/build-storefront.sh, theme:compile and the watch script during development, and commit the compiled dist folder for releases.
  • Use real controls, visible focus, live regions, good contrast and reduced-motion support.

Next, move from the shop front to the back office in The Administration at a Glance.