System Status

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:

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)",
	   ...
       }
       ...
  }
{
  "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'
    }
  }
};
PreviousPerforming actionsNextComponents

Last updated