--- title: Custom SCSS | Shopware Community Hub description: Learn how to customize the appearance of your Shopware Storefront using SCSS. canonical_url: 'https://hub.shopware.com/learn/unit/custom-scss' --- # Custom SCSS - Add custom SCSS to your Shopware theme. - Understand the hierarchy of SCSS files in Shopware. - Know where to add custom SCSS files. - Know how to use Bootstrap in Shopware. # Custom SCSS One of the first things you hear when a new shop is created is that the design is not quite right. The colors are not matching the brand, and the font might not be the right one. This is where SCSS comes into play. SCSS is a powerful **CSS preprocessor** to customize the appearance of your Shopware shop. Some basic visual settings, such as logos or new colors, can be changed through the **theme configuration** in the administration. For anything beyond these basic options – for example, detailed typography, custom layouts, or component-specific styling, you typically use **SCSS**. ## SCSS Folder Structure Before we start with adding all sorts of SCSS files, let's have a look at the folder structure. Typically, you start with just a few color and padding changes, but this can quickly grow into a big project. So it is good to know where to put your files and what folders you should use. Shopware recommends following the [7–1 pattern](https://sass-guidelin.es/#architecture). This means you have **seven folders and one file**. The folders are: The folder structure here follows the **7–1 pattern** as a recommended best practice for organizing large SCSS codebases. Shopware does **not** generate these folders automatically when creating a new theme. Files such as `utils/_variables.scss`, `utils/_mixins.scss`, or component-level SCSS files only exist if you create them yourself as part of your own structure. ```text └── custom └── plugins └── MyTheme └── src └── Resources └── app └── storefront └── src └── scss ├── base ├── components ├── layout ├── pages ├── themes ├── utils └── vendors ``` All SCSS files belong under `src/Resources/app/storefront/src/scss`. The **main file** is the **`base.scss`**, which acts as the **entry point** for your SCSS code. It should import all the other files, keeping your styles **modular**, **organized**, and **easy to maintain**. For more details on SCSS in Shopware, check out the [official docs](https://developer.shopware.com/docs/guides/plugins/themes/add-css-js-to-theme.html#adding-custom-scss). If you are unsure of what to put in which folder, check out the shopware repository on [GitHub](https://github.com/shopware/shopware/tree/trunk/src/Storefront/Resources/app/storefront/src/scss) or check out where specific CSS changes are put in the browser developer console. Here is an example of a common SCSS folder structure inside a plugin. ### Example: SCSS Folder Structure in a Plugin ```text ├── composer.json └── src ├── Resources │ └── app │ └── storefront │ └── src │ └── scss │ ├── base.scss // SCSS entry │ ├── base │ │ ├── _typography.scss │ │ └── ... │ ├── components │ │ ├── _buy-widget.scss │ │ ├── _promotion-section.scss │ │ ├── _cross-selling-slider.scss │ │ └── ... │ ├── layout │ │ ├── _main-navigation.scss │ │ ├── _grid.scss │ │ ├── _header.scss │ │ ├── _footer.scss │ │ └── ... │ ├── pages │ │ ├── _product-detail.scss │ │ ├── _checkout.scss │ │ ├── _account.scss │ │ ├── _startpage.scss │ │ └── ... │ ├── themes │ │ ├── _brand-default.scss │ │ ├── _dark-mode.scss │ │ └── ... │ ├── utils │ │ ├── _variables.scss │ │ ├── _mixins.scss │ │ └── ... │ └── vendors │ └── _vendor-lib.scss │ └── AcademyCustomCss.php ``` Each folder has a clear purpose: - The **`base`** subfolder: In this folder, you can create SCSS files which belong to the base of your shop, like the typography. - The **`components`** subfolder: In this folder, you can create SCSS files which belong to a specific UI component, like the buy-widget or sliders. - The **`layout`** subfolder: In this folder, you can create SCSS files which belong to the layout of your shop, like the header, footer, main navigation, or the grid. - The **`pages`** subfolder: In this folder, you can create SCSS files which belong to a specific shop page, like the product-detail-page or the startpage, for layout changes. - The **`themes`** subfolder: In this folder, you can create SCSS files which belong to a specific theme, like the brand-default, the brand-custom, or for Dark/Light mode. - The **`vendors`** subfolder: In this folder, you can create SCSS files to integrate external SCSS libraries. For example, Shopware Core uses it like this to import Bootstrap. - The **`utils`** subfolder: In this folder, you can create helper SCSS files such as variables and mixins which are used across all of your SCSS files. In a custom 7–1 based setup, the **`utils`** folder often contains two key files that you create yourself: - The **`variables.scss`** file is used to define global values for your Shop like colors, spacing, breakpoints, font sizes. - The **`mixins.scss`** files is used to define reusable functions (mixins) that can be included in other SCSS files. ```scss // In variables.scss $shop-primary-color: #0d6efd; // Shop's primary color $shop-secondary-color: #6c757d; // Shop's secondary color $shop-tertiary-color: #20c997; // Shop's tertiary color $shop-primary-color-negative: #ffffff; // Shop's primary color negative $spacer: 1rem; ``` - The `mixins.scss` file is used to define reusable functions. You can use `@mixin` to define a function and `@include` to use it. In addition, you can mix it with `media queries` to define different styles for different screen sizes. ```scss // In mixins.scss @mixin respond-to($breakpoint) { @if $breakpoint == sm { @media (max-width: 576px) { @content; } } @if $breakpoint == md { @media (max-width: 768px) { @content; } } } @mixin clearfix { &::after { content: ""; display: table; clear: both; } } //Usage in another file .my-container { @include respond-to(md) { padding: $spacer; } } ``` In the `base.scss` file, you can import all the other files. It will look like this: ```scss // In base.scss /* Utils */ @import "utils/variables"; @import "utils/mixins"; /* Optional: vendors */ @import "vendors/vendor-lib"; /* Base and Layout */ @import "base/typography"; @import "layout/main-navigation"; @import "layout/header"; @import "layout/footer"; @import "layout/grid"; /* Components */ @import "components/buy-widget"; @import "components/promotion-section"; @import "components/cross-selling-slider"; /* Pages */ @import "pages/product-detail"; @import "pages/checkout"; @import "pages/account"; @import "pages/startpage"; /* Optional: Themes */ @import "themes/brand-default"; @import "themes/dark-mode"; ``` In modern Sass (Dart Sass), **`@import`** is deprecated and replaced by `@use` / `@forward`. However, Shopware does not use Dart Sass. It uses [scssphp](https://scssphp.github.io/scssphp/), a PHP-based SCSS compiler supports more advanced functionality and relies on the **`@import`** syntax. That's why you will see `@import` consistently in Shopware projects, and it's the correct approach here. ## Adding the Right SCSS File You can use our example plugin from the [GitHub repository](https://github.com/ShopwareAcademy/AcademyCustomCss) or create it from scratch to get more familiar with the process. ```shell git clone --branch LU-01-custom-css git@github.com:ShopwareAcademy/AcademyCustomCss.git ``` Your shop should now have a blue background. ![Blue background](assets/scssBlueBackground.jpg) It is pretty basic, but it shows you how to add a custom SCSS file to your theme. You can use a theme, a plugin or an app to achieve that. The SCSS file will be compiled and added to your shop. If you are unsure of what is best for your use case, check out this [article](https://hub.shopware.com/learn/unit/shopware-extensions). If you are planning to override default colors, fonts, or paddings, you should use a theme. If you are planning to add a new feature that just has some styling, you should use a plugin or app. ## Troubleshooting Issues with SCSS not showing up in your shop? Here are some common problems: - Is your theme, plugin, or app installed and activated? - Plugin and Theme: `bin/console plugin:install --activate ` - App: `bin/console app:install --activate ` - Did you assign the right theme to your shop (`bin/console theme:change`)? - Did you add the SCSS file to the right location? - Did you recompile the Theme (`bin/console theme:compile`)? - Did you clear the cache (`bin/console cache:clear`)? ## Finding the Right SCSS File If you have multiple extensions installed, finding the right SCSS file can be a bit tricky. You have to know where to look and what to look for. The best way to find the right SCSS file is to use the browser developer console. But this is only possible in the watching mode. So you have to start the watcher and then open the developer console. Then you can inspect the elements and see which SCSS file is responsible for the styling. If, for example, you are inspecting the body tag in the default compiled theme, this will only show the `all.css` file. This is because the `all.css` file is the compiled version of all the SCSS files. If you want to see the SCSS file responsible for the body tag, you have to inspect the body tag in the watcher mode. For that, run the following command in your shop's root directory: ```shell bin/watch-storefront.sh ``` If you are using **DevEnv**, make sure you start the watcher **inside** the DevEnv shell: ```shell devenv shell ``` Then run the watcher from your shop's root directory. If you are using a custom environment setup, you might need additional configuration for the watcher. In this case, please refer to your environment's documentation, as the required steps may differ. This will start the watcher, and you can now inspect the body tag and see which SCSS file is responsible for the styling. The watcher recompiles your SCSS files automatically when you make changes. The default Port for the watcher is `9998`, so you can open the developer console at `localhost:9998` and inspect the body tag. The storefront watcher script relies on a few tools being available in your environment: `Node.js`, `npm`, and `jq`. If `bin/watch-storefront.sh` fails or exits immediately, double-check that these tools are installed. ![Inspect body tag](assets/customCssBackgroundColor.jpg) ## Usage Example: Remove Border in Product Listing Boxes The blue background might be a little much, but quickly shows that the SCSS file is working. Now let's do something more useful. We will remove the border from the product boxes in the listing and add a background color to the main navigation. This emphasizes the products more and makes the navigation more visible. ```scss .product-box { border:0; } .main-navigation { background-color: #ececec; } ``` ```shell cd custom/plugins/AcademyCustomCss git checkout -b LU-01-custom-css-navigation cd ../../.. && bin/console theme:compile ``` ![Product boxes without border](assets/removeBorderAndChangeNavigationBackgroundColor.jpg) This is where we leave off for now. We will continue with this in the next course, [Theme development](/learn/course/shopware-frontend-theme-development). ## Excursus: Bootstrap Shopware uses [Bootstrap](https://getbootstrap.com/) as its CSS framework. This means you don't need to install Bootstrap by yourself. Bootstrap provides a lot of useful responsive components, grid system and utility classes and much more. This means you don't need to write everything from scratch by yourself. Typically, you use Bootstrap directly in your HTML Elements. For example, to create a grid layout and add buttons. ### Example: Grid System ```twig

Column at left

Column in middle

Column at right

``` The `row` class is used to create a row. The `col-md-4` class is used to create a column with a width of 4. The maximum width is 12, so you have a row with three same-sized columns. If you, for example, want only two columns, you can use `col-md-6`. ```twig

Column at left

Column at right

``` ### Example: Buttons ```twig
Primary Secondary Success Danger Warning Info Light Dark Link
``` The `btn` class is used to create a button. The `btn-primary` class is used to create a primary button and so on. You can find a list of all available classes [here](https://getbootstrap.com/docs/5.3/components/buttons/#button-tags). ### Example: Utility Classes You can use utility classes to change the appearance of your elements. For example, for [text alignment](https://getbootstrap.com/docs/5.3/utilities/text/#text-alignment) or for [margin and padding](https://getbootstrap.com/docs/5.3/utilities/spacing/#margin-and-padding). ```twig

Centered text

Right aligned text

Left aligned text

``` These are a few examples. Bootstrap offers much more. To dive deeper into Bootstrap, check out the [official documentation](https://getbootstrap.com/docs/5.3/examples/). ## Summary In this learning unit, you learned how to: - Organize SCSS files in a Shopware plugin or theme using the **7–1 pattern**. - Define global variables and mixins for consistent and reusable styling. - Add and compile custom SCSS into your Shopware Storefront. - Use a watcher to debug and identify SCSS sources. - Leverage Bootstrap's grid, components, and utility classes. With this knowledge, you can start adapting the Shopware Storefront design to match brand requirements and build more maintainable styles.