Defining experience

Gain a better understanding of how to use the experience object to style a Prebuilt Checkout

In options.style, you can use experience to assign values to the properties of the CSS selectors that control Prebuilt Checkout's appearance and visual behavior.

When defining a create checkout-session request, you can also assign the experience object to style .

On this page, you'll find:

For details on how to perform even more granular styling of the payment collection stage, refer to Define the payment experience on the Configuring Prebuilt Checkout.

Primary parts of experience

  • At the experience level are styles, which control Prebuilt Checkout's general, overall appearance, such as its backgroundColor and fonts, as well as the color and roundness of its border. At this level, you can also define a logo. At the next level down in experience are elements and sections.

  • elements are the various parts of the experience, such as progressBars, headings, text, tables, separators, links, textFields, checkboxes, radioButtons, and buttons.

  • sections are the various stages that users might pass through while checking out, along with the header and footer they see during each stage. With the exception of header, all sections have elements.

  • The keys in the JSON correspond to a CSS property. The following are some common keys in the experience object and the CSS property that their value defines:

  • You can add pseudo-class keywords to change how something is styled based on its state or condition, such as when a user clicks a checkbox, hovers over a button or selects a payment method or when a value is determined to be invalid. In most cases, you define these keywords in elements.

"textFields": {
   ...
   ":hover": {
      "borderColor": "black"
   },
   ":focus": {
      "borderColor": "#00a7e1"
   },
   ":invalid": {
      "borderColor": "rgb(211, 47, 47)",
      "errorMessageColor": "rgb(211, 47, 47)"
   }
}

The following table captures examples of various styles you can control:

Styling express payment methods

You can use expressCheckout to style the various payment method buttons which display in that section.

payPal

googlePay

applePay

amazonPay

The rules of experience

The structure of experience determines which styles take precedence in the CSS. Generally, styles at a lower-level in the JSON hierarchy take precedence over styles at a higher level:

  • A style in elements overrides that style in experience

"experience": {
   ...
   "color": "#eb34de",
   ...
   "elements": {
       ...
      "text": {
          "color": "rgba(0, 0, 0, 0.87)",
	   ...
       }
       ...
  }
{
  "experience": {
    ...
    "elements": {
      ...
      "checkboxes": {
        "color": "rgba(0, 0, 0, 0.6)",
        ":checked": {
          "color": "#003058"
        },
        ...
      },
      ...
    },
    ...
    }
  }
}
  • A style in sections overrides that style in experience

{
  "experience": {
    ...
    "borderRadius": "30px",
    ...
    "sections": {
      ...
      "addressInformation": {
        "elements": {
          ...
          "textFields": {
            "borderRadius": "4px",
            ...
          },
          ...
        }
      },
      ...
    }
  }
}
  • A style in an elements of sections overrides that style in the corresponding elements

{
  "experience": {
    ...
    "elements": {
      ...
      "textFields": {
        ...
        "borderColor": "rgba(19, 0, 5, 0.23)",
        ...
      },
      ...
    },
    "sections": {
     ...
      "addressInformation": {
        "elements": {
          ...
          "textFields": {
            ...
            "borderColor": "rgba(0, 0, 0, 0.23)",
	     ...
          },
          ...
        }
      },
      ...
    }
  }
}
  • A pseudo-class selector style in an elements of sections overrides that pseudo-class selector style in the corresponding elements

{
  "experience": {
    ...
    "elements": {
      ...
      "textFields": {
        ...
        ":hover": {
          "borderColor": "black"
        },
        ...
      },
      ...
    },
    "sections": {
     ...
      "addressInformation": {
        "elements": {
          ...
          "textFields": {
            ...
            ":hover": {
              "borderColor": "blue"
            },
            ...
          },
          ...
        }
      },
      ...
    }
  }
}

The complete experience

The following is an example of the full experience object.

{
  "experience": {
    "logo": "https://www.digitalriver.com/wp-content/themes/digital-river-2022/assets/images/digital-river-logo-black-blue.svg",
    "backgroundColor": "#f0f4fa",
    "borderRadius": "30px",
    "borderColor": "rgba(0, 0, 0, 0.23)",
    "color": "#212121",
    "secondaryColor": "#757575",
    "fontFamily": "Kumbh Sans, Roboto,Arial, sans-serif",
    "fontStyle": "normal",
    "letterSpacing": "0",
    "elements": {
      "progressBars": {
        "previous": {
          "fill": "#003058",
          "color": "#003058"
        },
        "current": {
          "fill": "#003058",
          "color": "#003058"
        },
        "future": {
          "fill": "rgba(0, 0, 0, 0.38)",
          "color": "rgba(0, 0, 0, 0.6)"
        }
      },
      "headings": {
        "color": "#212121"
      },
      "text": {
        "color": "rgba(0, 0, 0, 0.87)",
        "fontSize": "0.875rem",
        "fontStyle": "normal",
        "label": {
          "fontWeight": 600
        }
      },
      "separators": {
        "color": "rgba(0, 0, 0, 0.12)"
      },
      "links": {
        "color": "#00a7e1",
        "textDecoration": "underline rgba(0, 0, 0, 0)",
        "footer": {
          "color": "#fff",
          "textDecoration": "underline rgba(0, 0, 0, 0)"
        }
      },
      "textFields": {
        "borderRadius": "4px",
        "borderColor": "rgba(0, 0, 0, 0.23)",
        "backgroundColor": "transparent",
        "color": "black",
        ":hover": {
          "borderColor": "black"
        },
        ":focus": {
          "borderColor": "#00a7e1"
        },
        ":invalid": {
          "borderColor": "rgb(211, 47, 47)",
          "errorMessageColor": "rgb(211, 47, 47)"
        },
        "label": {
          "color": "rgba(0, 0, 0, 0.87)",
          "fontSize": "0.875rem",
          "fontStyle": "normal"
        }
      },
      "checkboxes": {
        "color": "rgba(0, 0, 0, 0.6)",
        ":checked": {
          "color": "#003058"
        },
        "label": {
          "color": "rgb(33, 33, 33)"
        }
      },
      "radioButtons": {
        "color": "rgba(0, 0, 0, 0.6)",
        ":checked": {
          "color": "#003058"
        },
        ":focus": {
          "legend": {
            "color": "#00a7e1"
          }
        },
        "label": {
          "color": "rgb(33, 33, 33)",
          "fontStyle": "normal"
        },
        "legend": {
          "color": "rgba(0, 0, 0, 0.6)",
          "fontStyle": "normal"
        }
      },
      "buttons": {
        "forward": {
          "color": "#fff",
          "backgroundColor": "rgb(0, 48, 88)",
          ":hover": {
            "backgroundColor": "rgb(0, 167, 225)",
            "textColor": "#aed9f2",
            "boxShadow": "rgba(0, 0, 0, 0.2) 0px 2px 4px -1px, rgba(0, 0, 0, 0.14) 0px 4px 5px 0px, rgba(0, 0, 0, 0.12) 0px 1px 10px 0px"
          },
          ":active": {
            "boxShadow": "rgba(0, 0, 0, 0.2) 0px 5px 5px -3px, rgba(0, 0, 0, 0.14) 0px 8px 10px 1px, rgba(0, 0, 0, 0.12) 0px 3px 14px 2px"
          }
        },
        "back": {
          "color": "#212121",
          "backgroundColor": "transparent",
          ":hover": {
            "backgroundColor": "rgba(25, 118, 210, 0.04)"
          }
        },
        "edit": {
          "color": "#212121"
        }
      }
    },
    "sections": {
      "header": {
        "backgroundColor": "transparent",
        "showLogo": true
      },
      "footer": {
        "backgroundColor": "#001c33",
        "color": "#fff",
        "elements": {
          "links": {
            "textDecoration": "underline rgba(0, 0, 0, 0)",
            "color": "#fff"
          }
        }
      },
      "orderSummary": {
        "backgroundColor": "rgb(245, 247, 249)",
        "color": "black",
        "secondaryColor": "#757575",
        "elements": {
          "headings": {
            "fontWeight": 600,
            "color": "black"
          },
          "tables": {
            "productName": {
              "fontWeight": 600
            },
            "total": {
              "fontWeight": 600
            }
          }
        }
      },
      "expressCheckout": {
        "elements": {
          "headings": {
            "color": "black"
          }
        },
        "payPal": {
          "label": "checkout",
          "size": "responsive",
          "color": "gold",
          "shape": "pill"
        },
        "applePay": {
          "buttonType": "plain",
          "buttonColor": "dark"
        },
        "googlePay": {
          "buttonType": "plain",
          "buttonColor": "dark"
        },
        "amazonPay": {
          "buttonColor": "Gold"
        }
      },
      "addressInformation": {
        "elements": {
          "headings": {
            "color": "rgb(33, 33, 33)"
          },
          "textFields": {
            "borderRadius": "4px",
            "borderColor": "rgba(0, 0, 0, 0.23)",
            "backgroundColor": "transparent",
            "color": "black",
            ":hover": {
              "borderColor": "black"
            },
            ":focus": {
              "borderColor": "#00a7e1"
            },
            ":invalid": {
              "borderColor": "rgb(211, 47, 47)",
              "errorMessageColor": "rgb(211, 47, 47)"
            }
          },
          "checkboxes": {
            "color": "rgba(0, 0, 0, 0.6)",
            ":checked": {
              "color": "#003058"
            },
            "label": {
              "color": "rgb(33, 33, 33)"
            }
          }
        }
      },
      "shippingChoice": {
        "borderRadius": "4px",
        "elements": {
          "text": {
            "color": "rgb(33, 33, 33)",
            "fontSize": "0.875rem",
            "fontStyle": "normal",
            "label": {
              "fontWeight": 600
            }
          },
          "radioButtons": {
            "color": "rgba(0, 0, 0, 0.6)",
            ":checked": {
              "color": "#003058"
            },
            "label": {
              "color": "rgb(33, 33, 33)"
            }
          }
        }
      },
      "taxIdentifiers": {
        "elements": {
          "text": {
            "color": "rgb(33, 33, 33)",
            "fontSize": "0.875rem",
            "fontStyle": "normal",
            "label": {
              "fontWeight": 600
            },
            "appliedTaxIdentifier": {
              "color": "rgb(33, 33, 33)",
              "fontSize": "1.2rem",
              "fontStyle": "normal",
              "fontWeight": 400,
              "label": {
                "color": "rgba(0, 0, 0, 0.6)",
                "fontSize": "1rem",
                "fontStyle": "normal",
                "fontWeight": 400
              }
            }
          },
          "textFields": {
            "borderRadius": "4px",
            "borderColor": "rgba(0, 0, 0, 0.26)",
            "color": "rgb(33, 33, 33)",
            "label": {
              "color": "rgb(33, 33, 33)",
              "fontSize": "1rem",
              "fontStyle": "normal"
            }
          },
          "links": {
            "color": "#00a7e1",
            "textDecoration": "underline rgba(0, 0, 0, 0)"
          },
          "checkboxes": {
            "color": "rgba(0, 0, 0, 0.6)",
            ":checked": {
              "color": "#003058"
            },
            "label": {
              "color": "rgb(33, 33, 33)"
            }
          },
          "headings": {
            "color": "rgb(33, 33, 33)"
          },
          "radioButtons": {
            "color": "rgba(0, 0, 0, 0.6)",
            ":checked": {
              "color": "#003058"
            },
            ":focus": {
              "legend": {
                "color": "#00a7e1"
              }
            },
            "label": {
              "color": "rgb(33, 33, 33)",
              "fontStyle": "normal"
            },
            "legend": {
              "color": "rgba(0, 0, 0, 0.6)",
              "fontStyle": "normal"
            }
          }
        }
      },
      "payment": {
        "borderRadius": "4px",
        "paymentMethodName": {
          "color": "rgba(0, 0, 0, 0.75)",
          "fontSize": "1rem",
          "fontWeight": 400,
          "fontStyle": "normal",
          ":selected": {
            "color": "rgb(0, 167, 225)",
            "fontWeight": "bold",
            "fontStyle": "normal"
          }
        },
        "elements": {
          "text": {
            "color": "rgb(33, 33, 33)",
            "fontSize": "0.875rem",
            "fontStyle": "normal",
            "label": {
              "fontWeight": 600
            }
          },
          "textFields": {
            "borderRadius": "4px",
            "borderColor": "rgba(0, 0, 0, 0.26)",
            "color": "rgb(33, 33, 33)",
            "label": {
              "color": "rgba(0, 0, 0, 0.87)",
              "fontSize": "0.875rem",
              "fontStyle": "normal"
            }
          },
          "links": {
            "color": "#0000ee",
            "textDecoration": "underline",
            "footer": {
              "color": "rgba(0, 0, 0, 0.87)",
              "textDecoration": "none",
              ":hover": {
                "color": "#0000ee",
                "textDecoration": "underline"
              }
            }
          },
          "checkboxes": {
            ":checked": {
              "color": "#003058"
            },
            "label": {
              "color": "rgba(0, 0, 0, 0.87)"
            }
          }
        }
      }
    }
  }
}

Deprecated style objects

The experience object is our recommended styling solution. However, in options.style, you can alternatively define modal and textField.

const options = {
  style: {
    modal: {
      logo: 'https://www.mysite.com/logo.png',
      themeColor: {
        primary: '#00a7e1',
        highlight: '#b6e8fb',
        background: {
          header: '#b6e8fb',
          mainContent: '#fff',
          orderSummary: '#e4edf7',
          footer: '#001c33'
        },
        text: {
          link: '#003058',
          footerLink: '#0befc5',
          sectionHeading: '#083bf1',
          button: '#ffc439',
          textButton: '#0befc5'
        }
      },
      borderRadius: '3px',
      fontFamily: 'Arial, Helvetica, sans-serif',
      fontStyle: 'italic',
      fontVariant: 'normal',
      letterSpacing: '3px'
    },
    textField: {
      base: {
        color: '#00a7e1',
        fontFamily: 'Arial, Helvetica, sans-serif',
        fontSize: '20px',
        fontStyle: 'italic',
        fontVariant: 'normal',
        letterSpacing: '3px'
      },
      borderRadius: '4px'
    }
  }
};

Last updated