APIDeveloperUserRelease NotesDemoContact Us
  • Core

    • Addresses
    • Adjustments
    • Calculators
    • Inventory
    • Orders
    • Payments
    • Preferences
    • Products
    • Promotions
    • Shipments
    • Taxation
  • Customization

    • Storefront Customization
    • View Customization
    • Asset Customization
    • Images Customization
    • Dependency system
    • Logic Customization
    • Checkout Flow
    • API v2 Customization
    • API v1 Customization
    • Custom Authentication
    • Internationalization
    • Extensions
    • Emails Customization
  • Source

    • About the Code
    • Getting Help
    • Navigating the Source
  • Tutorials

    • Getting Started
    • Add Spree to an existing Ruby on Rails application
    • Developing Spree
    • Improve SEO
    • Creating an Extension
    • Deface Overrides
    • Extend Product Attributes
    • Security
    • Testing Spree Applications
    • Updating Extensions to Rails 6 and Spree 4
  • Upgrades

    • Upgrading Spree 4.1 to 4.2
    • Upgrading Spree 4.0 to 4.1
    • Upgrading Spree 3.7 to 4.0
    • Upgrading Spree from 3.6 to 3.7
    • Upgrading Spree from 3.5 to 3.6
    • Upgrading Spree from 3.4 to 3.5
    • Upgrading Spree from 3.3 to 3.4
    • Upgrading Spree from 3.2 to 3.3
    • Upgrading Spree from 3.1 to 3.2
    • Upgrading Spree from 3.0 to 3.1
    • All Upgrade Guides

Table Of Contents

OverviewStyling with SASS variablesHeaderFooterMeganav menuBackgroundBorder colorFontsInput fieldsPrimary colorSecondary colorGrid breakpointsRounding for componentsShadows for componentsGradient for componentsHeader and footer customizationLogo replacementMega menu categoriesSocial media icons in the footerContact us in the footerProduct categories in the footerReplacing placeholders with your images and copyHomepage placeholder slotsCategory banner on PLPProduct imagesMega menuSEO recommendationsSitemapSocial sharing and search preview

Storefront Customization

Overview

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

1

2

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 can 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

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

White

3

Blue

4

$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

5

Blue

6

White

7

Footer

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

8

9

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

10

11

Meganav menu

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

12

13

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

14

15

Background

$primary-background - the main background color across the whole site. There are two examples below, of the white and the black backgrounds. Please note that you can also use an image as a background.

16

17

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

18

19

20

21

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

22

23

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

24

25

Border color

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

26

27

28

29

30

31

32

33

34

35

Fonts

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

Input fields

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

36

37

38

39

40

41

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

42

43

44

Primary color

Home page

$primary-color variable changes

  • The color of the SHOP NOW button on the main hero image

45

  • The color of the Summer 2019 text and READ MORE button

46

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

47

Search results

$primary-color variable changes

  • The color of the No results icon

49

Mega Menu

$primary-color variable changes

  • The color of NEW COLLECTION and SUMMER SALE headers inside the banners

50

PDP

$primary-color variable changes

  • The color of the IN STOCK text

52

  • The color of the ADD TO CART button

53

Cart Page

$primary-color variable changes

  • The color of the Trash delete icon for removing items from the cart

54

  • The color of the CHECKOUT button

55

Cart pop-up

$primary-color variable changes

  • The color of the CHECKOUT and VIEW CART buttons

56

Cart - empty

$primary-color variable changes

  • The color of the CONTINUE SHOPPING button

57

  • The color of the Empty cart icon

58

Checkout - Registration Step

$primary-color variable changes

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

59

60

61

Checkout - Address step

$primary-color variable changes

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

62

  • The color of the Edit icon

63

Checkout - Payment step

$primary-color variable changes

  • The color of the APPLY button

64

Checkout - Confirm step

$primary-color variable changes

  • The color of the PLACE ORDER button

65

Sign-in page

$primary-color variable changes

The color of the LOG IN and SIGN UP buttons

66

67

Sign up page

$primary-color variable changes

  • The color of the SIGN UP and LOG IN buttons

68

69

My account page

$primary-color variable changes

  • The color of the Edit and Trash icons

70

Edit account page

$primary-color variable changes

  • The color of the UPDATE button

71

Pop-ups

$primary-color variable changes

  • The color of the CANCEL and OK buttons

72

Secondary color

PLP

$secondary-color variable changes

  • The color of the chosen color border variant

73

  • The color of the chosen size border variant

74

  • The color of the chosen length border variant

75

  • The color of the chosen price border variant

76

PDP

$secondary-color variable changes

  • The color of the chosen color border variant

77

  • The color of the chosen size border variant

78

  • The color of the chosen length border variant

79

  • The color of the chosen image border

80

Pop-ups

$secondary-color variable changes

  • The color of the Add to bag successfully icon

81

Log-in and Sign-in page

$secondary-color variable changes

  • The color of the Remember me checkbox

82

  • The color of the input: focus

83

Checkout

$secondary-color variable changes

  • The color of individual steps (box, name step, and guideline) - this element remains the same across the whole checkout process

84

Checkout - Address step

$secondary-color variable changes

  • The color of the Use shipping address checkbox

85

Checkout - Delivery step

$secondary-color variable changes

  • The color of delivery type radio buttons

86

Checkout - Payment step

$secondary-color variable changes

  • The color of payment type radio buttons

87

  • The color of payment card radio buttons

88

Order confirmation page

$secondary-color variable changes

  • The color of the successful checkmark icon

89

Grid breakpoints

Grid breakpoint variable allows you to slightly change element sizes on various devices. These changes are mostly to images and their scale ratio. Feel free to learn more from the Bootstrap manual, though 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

98

“False” example

99

Shadows for components

$enable-shadows - Enable shadow for components

Possible values: true or false

Gradient for components

$enable-gradients - Enable 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 your own 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 use a higher resolution, it will scale down automatically.

Mega menu categories

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.

Social media icons in the footer

Replace social media URLs with your own 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:

100

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.

Contact us in the footer

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.

Product categories in the footer

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 the Spree installer.

Replacing placeholders with your images and copy

You will need to replace various promo banner placeholder images, text, and buttons with your own. These changes are necessary on the homepage and on the following promo banners (each in four sizes listed on the following pages for various devices):

  • The main promo banner (“Summer Collection” and “SHOP NOW” button), as well as descriptions on all three category banners. These are the slider title (“BESTSELLERS”, “TRENDING”), the mid-page promo block (“FASHION TRENDS”), and the bottom promo banners (“STREETSTYLE”, “UP TO 60%“)
  • One category promo banner on the product listing page
  • Two promo banners for each main category on the meganav menu

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 four images for the various devices listed below. This is just the example for desktops.

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 four sizes for each of these promo banners:

Main banner

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

Big category banner

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

Upper and lower category banner

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

Left and right promotion banners

  • Promo banner 540 x 350 (desktop file)
  • Promo banner mobile 542 x 351 (mobile file)
  • Promo banner tablet landscape 470 x 305 (tablet landscape file)
  • Promo banner tablet portrait 734 x 476 (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 the app/assets/images/homepage folder. The files are automatically copied to your application folder after running the 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

Such 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 the line number where new image file names can be placed.

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 banner on PLP

The 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. See a full explanation of how to edit your products in the Spree guides.

The single product image will be automatically resized into multiple files and variations appropriate for different user devices will be utilized in the homepage carousels, on the product listing page (PLP), product detail page (PDP), cart pop-up, in the cart and order confirmation page.

Mega menu

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 the 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 called Spree Sitemap for that exact purpose.

  1. Per region, language or currency
  2. Click the Edit button (indicated with a pencil icon) for the right store
  3. Enter a title, keywords, and description values for the store homepage
  4. Click the Update button at the bottom of the page

101

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

  1. Go to Products > Taxonomies
  2. Go into the Categories list by pressing the Edit button (pencil icon)
  3. 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.

102

  1. Click the Edit link for that category
  2. Replace the default values for title, meta keywords, and description with your own
  3. Click the Update button at the bottom of the page

103

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

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

  1. Go to Products > Products
  2. In the product list pick the right one by pressing the Edit button (pencil icon)
  3. While in the Details tab, scroll down and input your values for the title, meta keywords, and description
  4. Click the Update button at the bottom of the page

104

Social sharing and search preview

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

  • Facebook sharing with Open Graph tags to enable an attractive 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.

Propose changes to this page
Designed and developed bySpree Commerce & Ruby on Rails developers© Spree Commerce. 2021 All Rights Reserved.