Integrate / Frames / Frames customization guide

Frames customization guide

Last updated: 14th July 2022

This page explains the different ways you can customize our Frames product.

Customize Frames

Frames can be rendered either as a single iframe (displayed as one input field) or as multiple iframes (displayed as multiple input fields).

Single and multiple iframes

In the single iframe case, the JavaScript library will dynamically apply an --invalid modifier to the container element class; in the multiple iframes case, the library will dynamically apply an --invalid modifier to each container element class.

Your checkout page can contain CSS declarations for styling the containers, such as to change the border color. For example, you can use the invalid modifier to render a red border if an invalid card number is entered.

The default approach is to hide the borders of input fields within the iframe input fields and style them within the checkout page as explained above, however, custom styling can be passed into Frames at initialization as shown below. This includes base, invalid, and placeholder styling options.

Localization

Make your customers feel at home by using our localization settings to change the language of your payment form. Use one of our pre-defined languages or create your own.

Pre-defined localization

If the language you would like to use appears in our pre-defined list, then just set the localization parameter, for example localization: 'FR-FR'.

The pre-defined languages are:

Arabic = AR
Chinese Simplified = ZH-CH
Chinese Traditional (Hong Kong) = ZH-HK
Chinese Traditional (Taiwan) = ZH-TW
Danish = DA-DK
Dutch = NL-NL
English = EN-GB
Filipino = FIL-PH
Finnish - FI-FI
French = FR-FR
German = DE-DE
Hindi = HI-IN
Indonesian = ID-ID
Italian = IT-IT
Japanese = JA-JP
Korean = KO-KR
Malay = MS-MY
Norwegian Bokmål = NB-NO
Spanish = ES-ES
Swedish = SV-SE
Thai = TH-TH
Vietnamese = VI-VN

Custom placeholders

Placeholders are defined by the selected localization. For further customization, you can pass an object to localization.

Frames.init({
  publicKey: 'pk_sbox_6ff46046-30af-41d9-bf58-929022d2cd14',
  localization: {
    cardNumberPlaceholder: 'Card number',
    expiryMonthPlaceholder: 'MM',
    expiryYearPlaceholder: 'YY',
    cvvPlaceholder: 'CVV',
  },
});

Custom CSS

If you want to override the default style of Frames and customize the input element's CSS, pass a style object to the init method.

Each specified rule name must be in camel case. For example, fontSize not font-size.

The table below lists all the available options.

Property name	Description
`base`	The default style.
`hover`	Rules applied when the element is hovered over.
`focus`	Rules applied when the element is focused.
`valid`	Rules applied when the element is valid.
`invalid`	Rules applied when the element is invalid.
`placeholder`	Accepts an object with `base` and `focus`.

We accept the majority of CSS rules (in camel case format), and the generated class names follow the BEM naming convention.

For example, an instance of Frames initialized with these values:

Frames.init({
  publicKey: 'YOUR-API-KEY',
  style: {
    base: {
      color: 'black',
      fontSize: '18px',
    },
    autofill: {
      backgroundColor: 'yellow',
    },
    hover: {
      color: 'blue',
    },
    focus: {
      color: 'blue',
    },
    valid: {
      color: 'green',
    },
    invalid: {
      color: 'red',
    },
    placeholder: {
      base: {
        color: 'gray',
      },
      focus: {
        border: 'solid 1px blue',
      },
    },
  },
});

Produces the following CSS rules:

.card-number {color: black;font-size: 18px;}
.card-number:-webkit-autofill {background-color: yellow;}
.card-number--autofilled {background-color: yellow;}
.card-number--hover {color: blue;}
.card-number--focus {color: blue;}
.card-number--valid {color: green;}
.card-number--invalid {color: red;}
input.card-number::-webkit-input-placeholder {color: gray;}
input.card-number::-moz-placeholder {color: gray;}
input.card-number:-ms-input-placeholder {color: gray;}
input.card-number--focus::-webkit-input-placeholder {border: solid 1px blue;}
input.card-number--focus::-moz-placeholder {border: solid 1px blue;}
input.card-number--focus:-ms-input-placeholder {border: solid 1px blue;}

.expiry-date {color: black;font-size: 18px;}
.expiry-date:-webkit-autofill {background-color: yellow;}
.expiry-date--autofilled {background-color: yellow;}
.expiry-date--hover {color: blue;}
.expiry-date--focus {color: blue;}
.expiry-date--valid {color: green;}
.expiry-date--invalid {color: red;}
input.expiry-date::-webkit-input-placeholder {color: gray;}
input.expiry-date::-moz-placeholder {color: gray;}
input.expiry-date:-ms-input-placeholder {color: gray;}
input.expiry-date--focus::-webkit-input-placeholder {border: solid 1px blue;}
input.expiry-date--focus::-moz-placeholder {border: solid 1px blue;}
input.expiry-date--focus:-ms-input-placeholder {border: solid 1px blue;}

.cvv {color: black;font-size: 18px;}
.cvv:-webkit-autofill {background-color: yellow;}
.cvv--autofilled {background-color: yellow;}
.cvv--hover {color: blue;}
.cvv--focus {color: blue;}
.cvv--valid {color: green;}
.cvv--invalid {color: red;}
input.cvv::-webkit-input-placeholder {color: gray;}
input.cvv::-moz-placeholder {color: gray;}
input.cvv:-ms-input-placeholder {color: gray;}
input.cvv--focus::-webkit-input-placeholder {border: solid 1px blue;}
input.cvv--focus::-moz-placeholder {border: solid 1px blue;}
input.cvv--focus:-ms-input-placeholder {border: solid 1px blue;}