Customise appearance

The mobile Payment Element supports visual customisation, which allows you to match the design of your app. The layout stays consistent, but you can modify colours, fonts, and more by including the appearance parameter when you call initPaymentSheet().

1. Start by customising the font
2. Customise colours to match your app
3. Customise shapes like the border radius
4. Fine-tune specific components

// The following code creates the appearance shown in the screenshot above
const customAppearance = {
 font: {
   family:
     Platform.OS === 'android' ? 'avenirnextregular' : 'AvenirNext-Regular',
 },
 shapes: {
   borderRadius: 12,
   borderWidth: 0.5,
 },
 primaryButton: {
   shapes: {
    borderRadius: 20,
   },
 },
 colors: {
   primary: '#fcfdff',
   background: '#ffffff',
   componentBackground: '#f3f8fa',
   componentBorder: '#f3f8fa',
   componentDivider: '#000000',
   primaryText: '#000000',
   secondaryText: '#000000',
   componentText: '#000000',
   placeholderText: '#73757b',
 },
};

const { error } = await initPaymentSheet({
 ...
 appearance: customAppearance,
});

Fonts

Customise the font by passing a FontConfig to font and setting family. On iOS, the value of family should be the “PostScript name” found in Font Book. On Android, copy the .ttf or .otf file from android/app/src/main/assets/font/<your-font> to android/app/src/main/res/font/<your-font> and use the name of the font file (containing only lowercase, alphanumeric characters). The Mobile Payment Element uses the font family of your custom font, but determines sizes and weights itself.

To increase or decrease the size of text, set scale. We multiply font sizes by this value before displaying them. This is useful if your custom font is slightly larger or smaller than the system font.

...
const appearance: AppearanceParams = {
   font: {
     family: Platform.OS === 'android' ? 'avenirnextregular' : 'AvenirNext-Regular',
     scale: 1.15,
   },
 },

Colours

Customise the colours in the mobile Payment Element by modifying the colour categories defined in Appearance.Colors. Each colour category determines the colour of one or more components in the UI. For example, primary defines the colour of the Pay button and selected items like the Save this card tickbox. Refer to the diagram below to see some of the UI elements associated with each colour category.

Shapes

Besides fonts and colours, you can also customise the border radius, border width, and shadow used throughout the mobile Payment Element.

Specific UI components

The previous sections describe customisation options that affect the mobile Payment Element broadly, across multiple UI components. We also provide customisation options specifically for the primary button (for example, the Pay button). Refer to the PrimaryButtonConfig for the full list of customisation options.

Customisation options for specific UI components take precedence over other values. For example, primaryButton.shapes.borderRadius overrides the value of shapes.borderRadius.