Getting Started
About Stencil
Transitioning to Stencil
Installing Stencil
Authentication & Tokens
Running Stencil Locally
Advanced Installation Options
Handlebars and Stencil
Handlebars Helpers
Stencil Object Model
Stencil Objects

Enable and Restyle Optimized One-Page Checkout

Enable Optimized One Page Checkout

In order to customize Stencil’s Optimized One Page Checkout, you must first opt into BigCommerce’s Optimized One-Page Checkout option if your store is not already running on Optimized One Page Checkout. To do so, use the following steps:

  1. Update your Stencil CLI installation to the most-recent version, as outlined here.

  2. Enable Optimized One-Page Checkout in the store’s control panel, as shown below. For more details about using Optimized One-Page Checkout, see the Checkout Settings support article.

  3. Within your theme’s config.json file > meta section, make sure the features array includes the value customized_checkout, as shown below:

   "meta": {
     "features": [
  1. Within your theme’s <theme-name>/templates/pages/ subdirectory, paste in a clean, uncustomized copy of the checkout.html and order-confirmation.html files. You can find default templates for each file on our [Cornerstone Github Repository]:

Note: For Optimized One-Page Checkout to work properly, the order-confirmation.html template must be present in your theme. If this template is absent, shoppers will receive a server error upon submitting their order.(The corresponding template was named order-complete.html in earlier versions of Stencil themes. But that minimal template is not a substitute for the required current template.)

Choosing Optimized One Page Checkout in the Control Panel
Choosing Optimized One Page Checkout in the Control Panel
Step #2 in the above description

Working with the Optimized Checkout SCSS File

Cornerstone includes an SCSS file that styles the Optimized Checkout page. In your local installation, this file is located at <theme-name>/assets/scss/optimized-checkout.scss.

You can access the most recent version of this file in the Cornerstone repository (Github). All themes share the same stylesheet for the Optimized One-Page checkout, even those not based on Cornerstone, so this stylesheet applies universally across Stencil themes.

To customize the checkout page, you are free to change classes’ contents. However, do not nest elements, nor change any class names. BigCommerce imposes these restrictions because each class here maps to multiple Optimized Checkout elements. Changing the structure or naming would break updates available in future Optimized Checkout enhancements.

Configuring the Desktop Viewport

Within the optimized-checkout.scss file, to set up Optimized Checkout’s responsive features, you should configure the following breakpoint to define your preferred desktop viewport size:

    // TODO:
    // Configure media query to be 'desktop' breakpoint size
    // -----------------------------------------------------------------------------
    @media (min-width: 801px) {
        text-align: stencilString("optimizedCheckout-logo-position");

Classes Available for Customization

Below are the classes provided in Cornerstone’s optimized-checkout.scss file, with the corresponding page elements that they style. These class names and mappings are subject to change, so please check the inline comments in the optimized-checkout.scss file that you downloaded with your current Cornerstone release.

Class Styles This Optimized One-Page Checkout Element:
.optimizedCheckout-header Page header.
.optimizedCheckout-headingPrimary Top-level headings.
.optimizedCheckout-headingSecondary Certain lower-level elements, such as descriptions of cart items.
.optimizedCheckout-overlay Shipping Method box.
.optimizedCheckout-contentPrimary Body text in the desktop Order Summary/Order Confirmation (cart contents); drop-down-list items; and text that summarizes completed steps.
.optimizedCheckout-contentSecondary Text labels on check boxes, and lower-level text in the desktop Order Summary.
.optimizedCheckout-button--primary CONTINUE button and final PAY button.
.optimizedCheckout-button--secondary Edit buttons.
.optimizedCheckout-orderSummary Colors in the Order Summary mobile drawer/modal.
.optimizedCheckout-step Large step-number indicators on the page’s left side.
.optimizedCheckout-form-label Styles form fields like Email Address – the field’s text-label color.
.optimizedCheckout-form-input Styles form fields like Email Address – the entry box’s background and border colors.

Providing User Options in Theme Editor

As with other aspects of your theme’s styling, you can determine which aspects of Optimized One-Page Checkout users will be able to customize in Theme Editor.

In Stencil’s Cornerstone base theme, each class/property available in optimized-checkout.scss has a corresponding key/value pair in the config.json file. For examples of these key/value pairs, see this section.

For examples of Theme Editor graphical controls exposed to users through elements included in Cornerstone’s schema.json file, please see this section.