Storefront Customization

Overview

The new Spree UX is here for the taking. Feel free to customize it according to your needs: overall styling, header, footer, placeholder images and text, SEO settings.

Styling with SASS variables

Spree 4.x uses Bootstrap 4 with built-in Sass variables for global style preferences for easy theming and component changes.

All the Sass variables needed for customizing the new Spree UX are in the variables.scss file. Color variables listed there could be assigned any CSS color value:

HEX - example: #007bff
RGB-A - example: 0 123 255 1
HSL-A - example: 211 100% 50% 1
Color name - example: Blue

To make those changes live you need to update app/assets/stylesheets/spree/frontend/variables/variables.scss in your project directory with your values and then commit those changes to your project code repository.

$header-background - header background color variable with 2 examples: white and blue one. By default set with $primary-background value but feel to replace it with any other value in the variables.scss file.

White

Blue

$header-font-color- Header font color. By default set with $font-color value but feel to replace it with any other value in the variables.scss file.

Dark Grey

Blue

White

$footer-background - variable that overrides $primary-background and allows you to change footer color. See a white and a blue example below.

$footer-font-color - variable that overrides $font-color and allows you to change footer font color. See black and blue font examples below.

$meganav-background - variable that allows you to change the mega nav menu background color. By default meganav menu is set to $primary-background value but feel to replace it with any other value in the variables.scss file.

$meganav-font-color - font color variable in the mega nav menu. By default mega nav font color is set to $font-color value but feel to replace it with any other value in the variables.scss file.

Background

$primary-background - main background color across the whole site. Two examples below - a white one and a black one. Please note that you can also use an image as a background.

$secondary-background - second background color present across the whole site with examples attached below.

$font-color - this variable affects all fonts on $primary-background. Please see two examples below.

$secondary-font-color - affects all fonts on $secondary-background. By default set with $font-color value but feel to replace it with any other value in the variables.scss file.

Border color

$global-border-style - affects border and separator color throughout the whole site

Fonts

$font-family - sets the font family used across your site. By default it is Sans Serif but feel to replace it with any other value in the variables.scss file. Check out these font families you could use.

Input fields

$input-background - allows you to set a color for all input field backgrounds across the site. See two examples below - a white one and a yellow one.

$second-global-border - allows you to set a color for all input field borders across the whole site. See an example below with red input field borders.

Primary color

Home Page

$primary-color variable changes

The color of SHOP NOW button on the main hero image

The color of Summer 2019 and READ MORE button

The color of NEW COLLECTION & SUMMER SALE headers inside the categories section

Search Results

$primary-color variable changes

The color of No Results icon

$primary-color variable changes

The color of NEW COLLECTION & SUMMER SALE headers inside the banners

PDP

$primary-color variable changes

The color of IN STOCK text

The color of ADD TO CART button

Cart Page

$primary-color variable changes

The color of Trash delete icon

The color of CHECKOUT button

Cart pop-up

$primary-color variable changes

The color of CHECKOUT and VIEW CART buttons

Cart - empty

$primary-color variable changes

The color of CONTINUE SHOPPING button

The color of Empty Cart icon

Checkout - Registration Step

$primary-color variable changes

The color of LOG IN, SIGN UP and CONTINUE AS A GUEST buttons

Checkout - Address Step

$primary-color variable changes

The color of SAVE AND CONTINUE button (this element remains the same across the whole checkout process)

The color of EDIT icon

Checkout - Payment step

$primary-color variable changes

The color of APPLY button

Checkout - Confirm Step

$primary-color variable changes

The color of PLACE ORDER buttons

$primary-color variable changes

The color of LOG IN and SIGN UP buttons

$primary-color variable changes

The color of SIGN UP and LOG IN buttons

My Account Page

$primary-color variable changes

The color of Edit and Trash icons

Edit Account Page

$primary-color variable changes

The color of UPDATE button

Pop-ups

$primary-color variable changes

The color of CANCEL and OK buttons

Secondary color

PLP

$secondary-color variable changes

The color of chosen color border variant

The color of chosen size border variant

The color of chosen length border variant

The color of chosen price border variant

PDP

$secondary-color variable changes

The color of chosen color border variant

The color of chosen size border variant

The color of chosen length border variant

The color of chosen image border

Pop-ups

$secondary-color variable changes

The color of Add to bag successfully icon

Log-in and Sign-in page

$secondary-color variable changes

The color of Remember me checkbox

The color of input: focus

Checkout

$secondary-color variable changes

The color of individual steps (box, name step and guide line) - this element remain the same across whole checkout process

Checkout - Address Step

$secondary-color variable changes

The color of Use shipping address checkbox

Checkout - Delivery Step

$secondary-color variable changes

The color of delivery type radio buttons

Checkout - Payment Step

$secondary-color variable changes

The color of payment type radio buttons

The color of payment card radio buttons

Order confirmation page

$secondary-color variable changes

The color of successful checkmark icon

Grid breakpoints

Grid breakpoint variable allow you to slightly change element sizes on various devices - mostly images and their scale ratio. Feel free to learn more from the Bootstrap manual. We don’t recommend changing these values unless you really need to.

Rounding for components

$enable-rounded - Enable rounding for components.

Possible values: true or false

“True” example

“False” example

Shadows for components

$enable-shadows - Enable shadow for components

Possible values: true or false

Gradient for components

$enable-gradients - Enable gradient for components

Header and footer customization

Feel free to customize header and footer elements as outlined below.

Logo replacement

In order to replace the default Spree logo with yours please follow these steps in the Spree guides. We do recommend using 127x52 dimensions for your logo in the SVG, PNG or JPEG formats, however, if you would like to use a higher resolution it will scale down automatically.

Categories visible in the Megamenu are defined in the spree_storefront.yml. The file is automatically copied to config/spree_storefront.yml in your application directory.

Make sure that these categories are also defined in the Admin panel on your site. You will find them in the Products > Taxonomies menu. Learn more about categories (taxonomies and taxons) in the Spree guides.

Replace social media URLs with yours in the Spree admin panel by going to Configuration > Stores and editing (pencil icon) your store settings in the Social section.

Make sure to place the part of the URL trailing after .com/, for example:

You don’t have to use any slashes.

If you leave any of the Social fields empty the corresponding social media icon will disappear.

After setting the values you want just click the “Update” button at the bottom of the page. Then go to Configuration > General Settings and click the “Clear cache” button to see your updates on the frontend.

If you would like to replace the default social media icons you could replace images in this path: frontend/app/assets/images/facebook.svg <- default facebook icon. Make sure to use SVG files.

The footer contains a “Contact us” section with your store contact information. You can change the contents of this section in the _footer.html.erb file in lines 30 to 38. The file is automatically copied to shared/_footer.html.erb in your application directory.

The footer by default contains a list of product categories in your store. Feel free to change the contents of this section in the config/spree_storefront.yml. The file is automatically copied to your application after running Spree installer.

Replacing placeholders with your images and copy

You will need to replace promo banner placeholder images as well as some text (buttons, promo banners) with your own:

on the homepage
- multiple promo banners described below (each in 4 sizes listed on the following pages for various devices)
- text on the main promo banner (“Summer Collection” and “SHOP NOW” button), descriptions on all three category banners, slider title (“BESTSELLERS”, “TRENDING”), mid-page promo block (“FASHION TRENDS”), bottom promo banners (“STREETSTYLE”, “UP TO 60%”)
product listing page - one category promo banner
meganav menu - two promo banners for each main category

Homepage placeholder slots

In the screenshot below you’ll find homepage promo banner slots with the default image placeholders indicating desktop placeholder sizes in pixels. Please note that each of these placeholders requires 4 images for various devices listed below. This is just a desktop example.

Homepage text values may be replaced in your project repository in the /app/views/spree/home/index.html.erb. Please note that this file will be automatically copied to your project directory after running Spree installer.

You’ll need to upload 4 sizes for each of these promo banners:

Main banner

Main banner 1440 x 600 (this is a desktop file)
Main banner mobile 575 x 240 (this is a mobile file)
Main banner tablet landscape 992 x 413 (this is a tablet landscape file)
Main banner tablet portrait 768 x 320 (this is a tablet portrait file)

Big category banner 540 x 800 (this is a desktop file)
Big category banner mobile 262 x 388 (this is a mobile file)
Big category banner tablet landscape 470 x 696 (this is a tablet landscape file)
Big category banner tablet portrait 358 x 530 (this is a tablet portrait file)

Category banner 540 x 388 (this is a desktop file)
Category banner mobile 262 x 188 (this is a mobile file)
Category banner tablet landscape 470 x 338 (this is a tablet landscape file)
Category banner tablet portrait 358 x 257 (this is a tablet portrait file)

Left and right promotion banners

Promo banner 540 x 350 (this is a desktop file)
Promo banner mobile 542 x 351 (this is a mobile file)
Promo banner tablet landscape 470 x 305 (this is a tablet landscape file)
Promo banner tablet portrait 734 x 476 (this is a tablet portrait file)

Please find all the placeholder images and their size variations in this Google Drive folder for your reference.

In order to replace those placeholder images you will probably want to perform two operations:

change the file names in the app/views/spree/home/index.html.erb in your project repository
upload those images to your Spree project code repo into app/assets/images/homepage folder. The files are automatically copied to your application folder after running Spree installer, preserving the file name structure and just changing big_category_banner to your file name:
big_category_banner.jpg
big_category_banner_mobile.jpg
big_category_banner_tablet_landscape.jpg
big_category_banner_tablet_portrait.jpg

Those file names will be used in the srcset attribute which specifies the URL of the image to use for various screen sizes and orientations.

If you’d like to change the file names in the app/views/spree/home/index.html.erb please find below line number where to place new image files names.

Main banner code lines

Line 3:

data-src="<%= asset_path('homepage/main_banner.jpg') %>"

Line 4:

data-srcset="<%= image_source_set('homepage/main_banner') %>"

Big category banner code lines

Line 54:

data-src="<%= asset_path('homepage/big_category_banner.jpg') %>"

Line 55:

data-srcset="<%= image_source_set('homepage/big_category_banner') %>"

Both category banners code lines

Line 24:

data-src="<%= asset_path('homepage/category_banner_upper.jpg') %>"

Line 25:

data-srcset="<%= image_source_set('homepage/category_banner_upper) %>"

Line 37:

data-src="<%= asset_path('homepage/category_banner_lower.jpg') %>"

Line 38:

data-srcset="<%= image_source_set('homepage/category_banner_lower) %>"

Both promo banners code lines

Line 101:

data-src="<%= asset_path('homepage/promo_banner_left.jpg') %>"

Line 102:

data-srcset="<%= image_source_set('homepage/promo_banner_left.jpg) %>"

Line 121:

data-src="<%= asset_path('homepage/promo_banner_right.jpg') %>"

Line 122:

data-srcset="<%= image_source_set('homepage/promo_banner_right') %>"

Category product listing page (PLP) banner is displayed on the top of each product category. You need to upload just one such promo banner sized 1110 x 300 px through the admin panel. To do that in the Spree admin panel go to Products > Taxonomies and edit the category for which you’d like to replace an image.

Product images

Add a product image for each product in just one resolution (650 x 870) using the admin panel. Here’s a full explanation of how to edit your products in the Spree guides.

That single product image will be automatically resized into multiple files and its variations appropriate for the user’s device will be used in the homepage carousels, on the product listing page (PLP), product detail page (PDP), cart pop-up, in the cart and order confirmation page.

In order to modify category promo banners in the Mega nav menu (by default New Collection and Special Offers) you have to modify spree_storefront.yml. The file is automatically copied to your application after running Spree installer.

SEO recommendations

Sitemap

We highly recommend adding a sitemap to your site. It might affect how Google bot crawls your store pages. There is + an official extension Spree Sitemap for that exact purpose.

per region, language or currency
click the Edit button (indicated with a pencil icon) for the right store,
enter title, keywords and description values for that store homepage
click the Update button at the bottom of the page

To set title, meta keywords and description for each store category page (PLP), in the admin panel:

go to Products > Taxonomies
go into a Categories list by pressing the Edit button (pencil icon)
pick the category you’d like to edit by right-clicking (control + click on a Mac) a child in the tree to access the menu for adding, deleting or sorting a child.

click the Edit link for that category
replace the default values for title, meta keywords and description with your own
click the Update button at the bottom of the page

You’ll have to edit every category and subcategory to your liking in a similar fashion.

To set title, meta keywords and description for each product page (PDP), in the admin panel:

go to Products > Products
in the product list pick the right one by pressing the Edit button (pencil icon)
while in the Details tab, scroll down and place your values for title, meta keywords and description
click the Update button at the bottom of the page

The new Spree UX has the following social sharing features implemented:

Facebook sharing with Open Graph tags to enable a nice page preview
Google visibility with structured data using Schema.org with JSON-DL

Feel free to test the Open Graph tags implementation and the also test the Schema.org implementation for your store.

Edit this page on GitHub