How to Add Custom Theme Styles to BigCommerce Page Builder

6 min readSep 22, 2020

The BigCommerce Stencil theme framework gives developers access to Page Builder, a powerful tool used to customize a theme and fit each store’s unique brand. Adding customization options to your Stencil theme empowers merchants to personalize different features of their theme without the need for a developer.

In this tutorial, we will build out a simple color changing option to control the background color of our storefront footer. We will use a combination of Sass, CSS, and JSON in our implementation. In this demonstration, we’ll build an option constrained to CSS, this could be built on with JavaScript or other languages. There are almost endless possibilities that can be implemented to help make your theme stand out above the rest.

Modifying schema.json to Create a Custom Option

In order to add these customizations, we will need to add settings into the schema.json file. But first, let’s take a look at this file from the Cornerstone Theme and begin to break down the structure.

/cornerstone/schema.json

Below you can see how this nesting structure directly maps to the Page Builder:

Now that we have a basic understanding of how these correlate, we can go further into schema.json and start to create our option. To ensure merchants can easily find this color option, we will begin with labeling the top-level “Colors” and content key “Footer”.

Once this hierarchy is established we can now add our new option. For this example, we are going to create a color option that will change the Footer’s background color. Even though we are creating a color option today, the Stencil Page Builder can support the following data types:

color
font
select [drop-down list]
checkbox
imageDimension
Text

There are three components that we will need to add type, label, and id. The type will be one of the six mentioned above, and a label will help merchants find which setting they want to change. The last component is the id and will be used later when we alter the theme’s config.json file and stylesheet. Let’s add these into the schema.json as shown below.

/cornerstone/schema.json

Defining a Default Option with config.json

Another great feature of Stencil is that you can add multiple theme variations. For example, Cornerstone has three styles, Light, Bold, and Warm. The config.json file will allow you to easily add different default values without modifying different files for each Style. You will, however, need to include the ID into each style.

With the change made before now saved, we can move on to editing the config.json file. The config.json will define any default values (even if that is simply an empty string). As users select and save options within the Page Buidler, Stencil will automatically rewrite config.json to record new defaults for the theme. It’s important to remember that a schema.json setting without an id-matched config.json value will not appear to users in the Page Builder UI.

Since we are modifying the Cornerstone theme in today’s example, we will set a default value for each of its styles. For Cornerstone Light we will set the default Footer background color to red. To do this, we will need to add the id and corresponding hex code (#FF0000 for red).

], “settings”: { “footer-bg”: “#ff0000”,

If we scroll down a bit on the config.json file, we can locate the default value for the Bold and Warm variations and set Bold to blue (#0000FF) and Warm to green (#FF00FF) as shown below.

/cornerstone/config.json

Configuring the Sass Stylesheet

Before we can use the custom option we created, we must configure the theme’s stylesheet to read our option id. Since we are adding an option to modify the Footer’s background color, we will want to navigate to the footer.scss file which in Cornerstone is located in cornerstone/assets/scss/layouts/footer/_footer.scss. Here we can find the styling that controls the .footer class and add in our CSS to change the background color.

.footer { background-color: $footer-bg; border-top: container(“border”); padding: spacing(“double”) 0; }

You’ll notice the ‘$’ symbol is included in our ‘footer-bg’ declaration value. This is important for the Sass variable, and will need to be included in order for Stencil to dynamically set the color the merchant chose. Finally, we must configure the custom Handlebars helpers to transform the config.json entries into CSS values. To do this, we will navigate to the Footer’s _settings.scss file. This is found in Cornerstone under /cornerstone/assets/scss/settings/layouts/footer/_settings.scss.

Inside this file, you will need to include a custom Sass function. For our example, we will be using the stencilColor as shown below. However, if you are configuring a different type of option you will need to use a different Sass function. Our developer documentation has a useful stencilColor reference sheet if you don’t know which one to use.

/cornerstone/assets/scss/settings/layouts/footer/_settings.scss

Previewing the Change Locally

With our newly created option finished, we can go ahead and preview our work locally. To access the Page Builder UI locally, we will need to run the command stencil start -e in our terminal. This will allow us to view the Page Builder locally. Instead of using localhost:3000, we must navigate to localhost:8181.

We are now able to see the default setting for the Footer’s Background color is set to red (#FF0000) as we previously declared. Let’s change this and set the color to white (#FFF) using the Page Builder UI.

We have successfully created a custom option in our BigCommerce Stencil Theme! Merchants can now customize this option to fit their needs.

What about Widgets?

The BigCommerce Widgets API programmatically associates content with regions on a BigCommerce storefront. The content can consist of HTML, CSS, and JavaScript, and the Widgets API supports configuration via Handlebars variables. With the use of the Page Builder, merchants can drag and drop content like text, images, videos, banners, carousels, buttons, and blocks of custom HTML. You can find more information on Page Builder and the Widgets API on our Dev Center here.

Conclusion

Adding customization to any Stencil theme will benefit merchants looking to easily modify the appearance of their store and improves their user experience. While this post demonstrates only one example, I encourage you to take this experience and further explore the possibilities out there for customization. Try experimenting with a custom javascript or implementing an Instagram integration that allows Merchants to grow their social media reach.

Resources

I’ve included below some great resources and troubleshooting guides that can help you add options to your Stencil Theme.

I’m curious to see how others would use these helpers creatively! Share your ideas in the comments below or tweet us at @BigCommerceDevs and let us know how you’ve applied Handlebars Helpers to your Stencil themes lately.