# Customise appearance

Customise your in-app integration with the Appearance API.

# Android


The 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 creating your `EmbeddedPaymentElement.Configuration` object with an [appearance](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html#-431946322%2FProperties%2F2002900378) object.

1. Customise the [font](https://docs.stripe.com/elements/appearance-api/embedded-mobile.md#fonts-android)
2. Customise [colours](https://docs.stripe.com/elements/appearance-api/embedded-mobile.md#colors-android) to match your app
3. Customise [shapes](https://docs.stripe.com/elements/appearance-api/embedded-mobile.md#shapes-android) like corner radius
4. Fine-tune [specific components](https://docs.stripe.com/elements/appearance-api/embedded-mobile.md#specific-ui-components-android)
![](https://b.stripecdn.com/docs-statics-srv/assets/android-appearance-before-after-example-embedded.b22df0fed3d35c4cb58eed128d3511a2.png)

```kotlin
// The following code creates the appearance shown in the screenshot above
import androidx.compose.ui.graphics.Color

val appearance = PaymentSheet.Appearance(
   colorsLight = PaymentSheet.Colors(
       primary = Color(red = 36, green = 36, blue = 47),
       surface = Color.White,
       component = Color(red = 243, green = 248, blue = 245),
       componentBorder = Color.Transparent,
       componentDivider = Color.Black,
       onComponent = Color.Black,
       subtitle = Color.Black,
       placeholderText = Color(red = 115, green = 117, blue = 123),
       onSurface = Color.Black,
       appBarIcon = Color.Black,
       error = Color.Red,
   ),
   shapes = PaymentSheet.Shapes(
       cornerRadiusDp = 12.0f,
       borderStrokeWidthDp = 0.5f
   ),
   typography = PaymentSheet.Typography.default.copy(
       fontResId = R.font.avenir_next
   ),
   primaryButton = PaymentSheet.PrimaryButton(
   shape = PaymentSheet.PrimaryButtonShape(
            cornerRadiusDp = 20f
        ),
    ),
    embeddedAppearance = PaymentSheet.Appearance.Embedded(
        style = PaymentSheet.Appearance.Embedded.RowStyle.FloatingButton(
            spacingDp = 20f,
            additionalInsetsDp = 10f
        )
    )
)

// ...

embeddedPaymentElement.configure(
    intentConfiguration = intentConfiguration,
    configuration = EmbeddedPaymentElement.Configuration.Builder(merchantName)
        .appearance(appearance)
        .build()
)

```

## Fonts

Customise the font by setting [typography.fontResId](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-typography/index.html#-786783041%2FProperties%2F2002900378) to your custom font’s resource ID. 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 [typography.sizeScaleFactor](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-typography/index.html#1477076499%2FProperties%2F2002900378). Stripe multiplies font sizes by this value before displaying them. This setting is useful if your custom font is slightly larger or smaller than the system font.

```kotlin
val appearance = PaymentSheet.Appearance(
    // …
    typography = PaymentSheet.Typography.default.copy(
        sizeScaleFactor = 1.15f, // Increase the size of all text by 1.15x
        fontResId = R.font.myFont,
    ),
)
val configuration = EmbeddedPaymentElement.Configuration(merchantName).Builder()
    .appearance(appearance)
    .build()
```

## Colours

Customise the colours in the mobile Payment Element by modifying the colour categories defined in [PaymentSheet.Colors](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-colors/index.html). Each colour category determines the colour of one or more components in the UI. For example, [primary](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-colors/index.html#1242160296%2FProperties%2F2002900378) 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.

> To support dark mode, set [appearance.colorsDark](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-appearance/index.html#945237406%2FProperties%2F2002900378). You can effectively disable dark mode by setting [appearance.colorsDark](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-appearance/index.html#945237406%2FProperties%2F2002900378) to the same value as [appearance.colorsLight](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-appearance/index.html#2092498352%2FProperties%2F2002900378)
![](https://b.stripecdn.com/docs-statics-srv/assets/android-appearance-colors.413c76aaf01a54c25478cb8d7532c7e7.png)

## Shapes

In addition to customising fonts and colours, you can also customise the [corner radius](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-shapes/index.html#-1129752289%2FProperties%2F2002900378) and [border width](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-shapes/index.html#495484314%2FProperties%2F2002900378) used throughout the mobile Payment Element by setting [appearance.shapes](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-appearance/index.html#-2108514638%2FProperties%2F2002900378).
![](https://b.stripecdn.com/docs-statics-srv/assets/android-appearance-shapes-embedded.d484b1076a44aa65cf334d6d452edd7c.png)

## Specific UI components

The sections above 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 [Appearance.PrimaryButton](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-primary-button/index.html) for the full list of customisation options.

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

> If you have ideas for additional customisation options, [let us know](https://github.com/stripe/stripe-android/issues/new/choose).

## Payment Element

The Payment Element has the following styles: flat with radio buttons, flat with check marks, flat with disclosure and floating buttons. Each style has its own options.

### Flat with radio buttons

To use the flat with radio buttons style, set the `FlatWithRadio` properties as shown in the code example.
![Embedded payment element styled using flat with radio buttons](https://b.stripecdn.com/docs-statics-srv/assets/android-embedded-flat-with-radio.c458c8cea3eb4421b1f99a212961f464.png)

```kotlin
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.toArgb

val embeddedColors = PaymentSheet.Appearance.Embedded.RowStyle.FlatWithRadio.Colors(
    selectedColor = Color.Yellow.toArgb(), // Change color of radio button when selected to yellow
    unselectedColor = Color.DarkGray.toArgb(), // Change color of radio button when unselected to darkGray
    separatorColor = Color.Gray.toArgb(), // Change the separator color to gray
)
val embeddedAppearance = PaymentSheet.Appearance.Embedded.Builder()
    .rowStyle(
      PaymentSheet.Appearance.Embedded.RowStyle.FlatWithRadio.Builder()
        .separatorThicknessDp(2f) // Increase separator thickness to 2
        .startSeparatorInsetDp(0f) // Make start separator full width
        .endSeparatorInsetDp(0f) // Make end separator full width
        .topSeparatorEnabled(false) // Hide the top separator
        .bottomSeparatorEnabled(false) // Hide the bottom separator
        .additionalVerticalInsetsDp(10f) // Increase row height
        .horizontalInsetsDp(10f)
        .colorsLight(embeddedColors)
        .colorsDark(embeddedColors)
        .build()
    )
    .build()

val appearance = PaymentSheet.Appearance(
    embeddedAppearance = embeddedAppearance,
)

val configuration = EmbeddedPaymentElement.Configuration.Builder("Powdur")
    .appearance(appearance)
    .build()
```

### Flat with tickmarks

To use the flat with tickmarks style, set the `FlatWithCheckmark` properties, as shown in the code example.
![Embedded payment element styled using flat with tickmarks](https://b.stripecdn.com/docs-statics-srv/assets/android-embedded-flat-with-checkmark.c6ed2d5af6660be462e7e39e3736eb87.png)

```kotlin
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.toArgb

val embeddedColors = PaymentSheet.Appearance.Embedded.RowStyle.FlatWithCheckmark.Colors(
    checkmarkColor = Color.Blue.toArgb(), // Change color of the checkmark
    separatorColor = Color.Gray.toArgb(), // Change the separator color to gray
)
val embeddedAppearance = PaymentSheet.Appearance.Embedded.Builder()
    .rowStyle(
      PaymentSheet.Appearance.Embedded.RowStyle.FlatWithCheckmark.Builder()
        .separatorThicknessDp(2f) // Increase separator thickness to 2
        .startSeparatorInsetDp(0f) // Make start separator full width
        .endSeparatorInsetDp(0f) // Make end separator full width
        .topSeparatorEnabled(false) // Hide the top separator
        .bottomSeparatorEnabled(false) // Hide the bottom separator
        .checkmarkInsetDp(2f) // Inset the checkmark
        .additionalVerticalInsetsDp(10f) // Increase row height
        .horizontalInsetsDp(10f)
        .colorsLight(embeddedColors)
        .colorsDark(embeddedColors)
        .build()
    )
    .build()

val appearance = PaymentSheet.Appearance(
    embeddedAppearance = embeddedAppearance,
)

val configuration = EmbeddedPaymentElement.Configuration.Builder("Powdur")
    .appearance(appearance)
    .build()
```

### Flat with disclosure

To use the flat with disclosure style, set the `FlatWithDisclosure` properties, as shown in the code example below.

The FlatWithDisclosure style requires you to set the `immediateAction` row selection behaviour. After the customer selects a payment method, move them to a new screen (for example, back to your main checkout screen) because the row of their selected payment method won’t appear selected.
![Embedded payment element styled using flat with disclosure](https://b.stripecdn.com/docs-statics-srv/assets/android-embedded-flat-with-disclosure.b6753b90204debcaa6b5607375ae7fc1.png)

```kotlin
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.toArgb

// EmbeddedPaymentElement initialization

val embeddedBuilder = EmbeddedPaymentElement.Builder(
  ...,
)
  // The FlatWithDisclosure style requires the immediateAction row selection behavior, which accepts a handler for a user selecting a payment method.
  .rowSelectionBehavior(EmbeddedPaymentElement.RowSelectionBehavior.immediateAction { embeddedPaymentElement ->
    // Handle the customer tapping a payment method row here
  })

...

// Configuration

val embeddedColors = PaymentSheet.Appearance.Embedded.RowStyle.FlatWithDisclosure.Colors(
    disclosureColor = Color.Blue.toArgb(), // Change color of the disclosure
    separatorColor = Color.Gray.toArgb(), // Change the separator color to gray
)
val embeddedAppearance = PaymentSheet.Appearance.Embedded.Builder()
    .rowStyle(
      PaymentSheet.Appearance.Embedded.RowStyle.FlatWithDisclosure.Builder()
        .separatorThicknessDp(2f) // Increase separator thickness to 2
        .startSeparatorInsetDp(0f) // Make start separator full width
        .endSeparatorInsetDp(0f) // Make end separator full width
        .topSeparatorEnabled(false) // Hide the top separator
        .bottomSeparatorEnabled(false) // Hide the bottom separator
        .additionalVerticalInsetsDp(10f) // Increase row height
        .horizontalInsetsDp(10f)
        .colorsLight(embeddedColors)
        .colorsDark(embeddedColors)
        .build()
    )
    .build()


val appearance = PaymentSheet.Appearance(
    embeddedAppearance = embeddedAppearance,
)

val configuration = EmbeddedPaymentElement.Configuration.Builder("Powdur")
  .appearance(appearance)
  .build()
```

### Floating buttons

To use the floating buttons style, set the `FloatingButton` properties, as shown in the code example.
![Embedded payment element styled using floating button](https://b.stripecdn.com/docs-statics-srv/assets/android-embedded-floating-button.4cbe384dc61d18c8c3d053c3216e6f43.png)

```kotlin
val embeddedAppearance = PaymentSheet.Appearance.Embedded.Builder()
    .rowStyle(
      PaymentSheet.Appearance.Embedded.RowStyle.FloatingButton.Builder()
        .additionalInsetsDp(10f) // Increase row height
        .spacingDp(20f) // Increase spacing
    )
    .build()


val appearance = PaymentSheet.Appearance(
    embeddedAppearance = embeddedAppearance,
)

val configuration = EmbeddedPaymentElement.Configuration.Builder("Powdur")
    .appearance(appearance)
    .build()
```

### Common row customisations

You can customise row properties that apply across all row styles:

```kotlin
@OptIn(AppearanceAPIAdditionsPreview::class)
val embeddedAppearance = PaymentSheet.Appearance.Embedded.Builder()
    // Custom margins for the payment method icon (for example, the Klarna logo)
    .paymentMethodIconMargins(
      PaymentSheet.Insets(
        horizontalDp = 10f,
        verticalDp = 5f
      )
    )
    // Custom font for the row title (for example, "Klarna")
    .titleFont(
      PaymentSheet.Typography.Font(
        fontFamily = R.font.custom_font,
        fontSizeSp = 20f,
        fontWeight = 50,
        letterSpacingSp = 8f
      )
    )
    // Custom font for the row subtitle (for example, "Buy now or pay later with Klarna")
    .titleFont(
      PaymentSheet.Typography.Font(
        fontFamily = R.font.custom_font,
        fontSizeSp = 14f,
        fontWeight = 50,
        letterSpacingSp = 8f
      )
    )
    .build()

val appearance = PaymentSheet.Appearance(
    embeddedAppearance = embeddedAppearance,
)

val configuration = EmbeddedPaymentElement.Configuration.Builder("Powdur")
    .appearance(appearance)
    .build()
```