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:

• A description of the primary parts of experience

• Express payment method styling options

• The rules that govern experience

• The complete experience

• Deprecated style objects

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:

JSON key	CSS property
borderRadius	border-radius
backgroundColor	background-color
borderColor	border-color
textDecoration	text-decoration
fontStyle	font-style
fontFamily	font-family
letterSpacing	letter-spacing
color	color
fontSize	font-size
fontWeight	font-weight
boxShadow	box-shadow

• 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:

experience.logo
elements.progressBars.previous
elements.progressBars.current
elements.progressBars.future
elements.headings
elements.text
elements.separators
elements.links
elements.textFields
elements.textFields.label
elements.checkboxes
elements.checkboxes.label
elements.radioButtons
elements.radioButtons.label
elements.buttons.forward
elements.buttons.back
elements.buttons.edit
sections.header
sections.footer
sections.orderSummary
sections.expressCheckout For details, refer to Styling express payment methods.
sections.addressInformation
sections.shippingChoice
sections.taxIdentifiers
sections.payment
sections.payment.paymentMethodName

Styling express payment methods

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

payPal

Key	Description	Supported values
label	Customizes the button's label	paypal (default), pay, checkout, buynow
size	Sets the size of the button	responsive (default), small, medium, large
color	Sets the color of the button	gold (default), silver, black, white, blue
shape	Determines whether the button is pill or rectangular shaped	pill (default), rect

googlePay

Key	Description	Supported values
buttonType	Defines the button's label and type	plain (default), long
buttonColor	Defines the button's background color	dark (default), light

applePay

Key	Description	Supported values
buttonType	Defines the button's label and type	plain, buy
buttonColor	Defines the button's background color	light, light-outline, dark

amazonPay

Key	Description	Supported values
buttonColor	Defines the button's background color	Gold (default), LightGray, DarkGray

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)",
	   ...
       }
       ...
  }

• A pseudo-class selector style in elements overrides that style in the same elements

{
  "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'
    }
  }
};