## Use Elements with the Checkout Sessions API

[Stripe Elements](/payments/elements.md) are customizable UI
components you can use to build your checkout page.

Use the [Checkout](/js/custom_checkout.md)
instance to create and manage Elements.

## Create a Payment Form Element

This method creates an instance of a Payment Form Element.

This method returns the newly created Payment Form Element instance.

**Syntax:** `checkout.createPaymentFormElement(...)`

- `options` (object)
  Payment Form Element initialization options.

  - `layout` ('expanded' | 'compact')
    The layout of the Payment Form Element. The `'expanded'` layout is a single-step checkout form, while the `'compact'` layout is a multi-step checkout form. When you leave this undefined, Stripe renders the layout it determines has the best conversion.

  - `contacts` (array)
    An array of [Contact](/js/appendix/contact_object.md) objects that you can use to display saved addresses in the Payment Form Element. The first contact is automatically selected.

  - `expressCheckout` (object)
    Express checkout configuration options.

    - `buttonTheme` (object)
      Specify the preferred button theme to use. By default, Elements determines the themes based on the specified [appearance option](/js/elements_object/create.md#stripe_elements-options-appearance).

      - `applePay` ('black' | 'white' | 'white-outline')

      - `googlePay` ('black' | 'white')

      - `paypal` ('gold' | 'blue' | 'silver' | 'white' | 'black')

      - `klarna` ('dark' | 'light' | 'outlined')

    - `paymentMethods` (object)
      Besides your Dashboard configuration, the availability of payment methods in the Payment Form Element is influenced by the CheckoutSession configuration. By default, it displays all available payment methods based on both configurations. When setting the paymentMethods option, the Payment Form Element merges your specified options with the default logic to determine the final set of payment methods displayed.

      - `amazonPay` ('auto' | 'never')

      - `applePay` ('always' | 'auto' | 'never')
        Apple Pay has additional configurations
that determine when Stripe can show it. By default, Apple Pay shows when the customer
is using a supported platform and when we determine it's advantageous for your conversion.
This is the `auto` behavior.
If you want to always show Apple Pay when the customer is using a supported platform,
you can set its property in `paymentMethods` to `always`.

      - `googlePay` ('always' | 'auto' | 'never')
        Google Pay has additional configurations
that determine when Stripe can show it. By default, Google Pay shows when the customer
is using a supported platform and when we determine it's advantageous for your conversion.
This is the `auto` behavior.
If you want to always show Google Pay when the customer is using a supported platform,
you can set its property in `paymentMethods` to `always`.

      - `link` ('auto' | 'never')

      - `paypal` ('auto' | 'never')

### Create a Payment Form Element

```js
var element = checkout.createPaymentFormElement();
```

```es_next
const element = checkout.createPaymentFormElement();
```

## Create a Payment Element

This method creates an instance of a Payment Element.

This method returns the newly created Payment Element instance.

**Syntax:** `checkout.createPaymentElement(...)`

- `options` (object)
  Payment Element initialization options.

  - `fields` (object)
    By default, the Payment Element will collect only the necessary billing details to complete a payment.

If you intend to collect billing details fields outside of the Payment Element, you can disable Payment Element collection of certain fields with the `fields` option.

    - `billingDetails` ('never' | 'auto' | object)
      Specify `never` to avoid collecting all [billing details](/api/payment_methods/object.md#payment_method_object-billing_details)
in the Payment Element. If you would like to disable only certain billing details,
pass an object specifying which fields you would like to disable collection for.
The default setting for each field or object is `auto`.

      - `name` ('never' | 'auto')

      - `email` ('never' | 'auto')

      - `phone` ('never' | 'auto')

      - `address` ('never' | 'if_required' | 'auto' | object)
        Specify `if_required` to only collect the minimum billing address fields required to complete the payment.
You can omit and hide optional address fields in the card form, such as country and postal code.
Unlike the `never` option, you don't need to include fields omitted in the Payment Element when confirming the payment.
This can reduce the amount of information required to complete the form.

Disabling address collection can negatively impact authorization rates and network fees for users on a network cost plus pricing plan.

        - `line1` ('never' | 'auto')

        - `line2` ('never' | 'auto')

        - `city` ('never' | 'auto')
          The name of a city, town, village, etc.

        - `state` ('never' | 'auto')
          The most coarse subdivision of a country.
Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines.

        - `country` ('never' | 'auto')
          Two-letter country code, capitalized. Valid two-letter country codes are specified by ISO3166 alpha-2.

        - `postalCode` ('never' | 'auto')
          The postal code or ZIP code, also known as PIN code in India.

  - `layout` ('accordion' | 'tabs' | object)
    Specify the layout for the Payment Element. If you only pass a layout type (`'accordion'` or `‘tabs’`) without any additional parameters, the Payment Element renders using that layout and the default values associated with it.

An object can also be passed to specify the layout with additional configuration.

    - `type` ('accordion' | 'tabs') **required**
      Defines the layout to render the Payment Element.

    - `defaultCollapsed` (boolean)
      Controls if the Payment Element renders in a collapsed state (where no payment method is selected by default). When you leave this `undefined`, Stripe renders the experience that it determines will have the best conversion.

    - `radios` ('always' | 'never' | 'if_multiple' | 'auto')
      Controls when to render each Payment Method with a radio input next to its logo. The radios visually indicate the current selection of the Payment Element. Defaults to `'auto'`.

- `'always'` — Always show radio inputs.
- `'never'` — Never show radio inputs.
- `'if_multiple'` — Show radio inputs only when there are multiple payment methods available. When there is only one payment method, no radio input is displayed.
- `'auto'` — Stripe determines the best experience to optimize conversion.

_This property is only applicable to the `accordion` layout._

    - `spacedAccordionItems` (boolean)
      When `true`, the Payment Methods render as standalone buttons with space in between them.

_This property is only applicable to the `accordion` layout._

    - `visibleAccordionItemsCount` (number)
      Sets the max number of Payment Methods visible before using the "More" button to hide additional Payment Methods. Set this value to `0` to disable the "More" button and render all available Payment Methods. Default is `5`.

_This property is only applicable to the `accordion` layout._

    - `paymentMethodLogoPosition` ('start' | 'end')
      Sets the position of the payment method logo in each accordion item. Default is `start`.

_This property is only applicable to the `accordion` layout._

  - `paymentMethodOrder` (array)
    By default, the Payment Element will use a dynamic ordering that optimizes payment method display for each user.

You can override the default order in which payment methods are displayed in the Payment Element with a list of payment method types.

If the associated Checkout Session has payment method types not specified in `paymentMethodOrder`, they will be displayed
after the payment methods you specify. If you specify payment method types not on the associated PaymentIntent, they will be ignored.

  - `readOnly` (boolean)
    Applies a read-only state to the Payment Element so that payment details can’t be changed. Default is false.

Enabling the `readOnly` option doesn't change the Payment Element's visual appearance. If you want to adjust the way the Payment Element looks, use the [Appearance API](/elements/appearance-api.md).

  - `terms` (object)
    Control how mandates or other legal agreements are displayed in the Payment Element.
Use `never` to never display legal agreements. The default setting is `auto`, which causes
legal agreements to only be shown when necessary.

Consult your legal and compliance advisors before making any changes to the text of mandates or legal agreements. You can't use the `terms` option to violate obligations under your Stripe agreement, Stripe policies, applicable laws or scheme rules.

    - `applePay` ('auto' | 'always' | 'never')

    - `auBecsDebit` ('auto' | 'always' | 'never')

    - `bancontact` ('auto' | 'always' | 'never')

    - `card` ('auto' | 'always' | 'never')

    - `cashapp` ('auto' | 'always' | 'never')

    - `googlePay` ('auto' | 'always' | 'never')

    - `ideal` ('auto' | 'always' | 'never')

    - `paypal` ('auto' | 'always' | 'never')

    - `sepaDebit` ('auto' | 'always' | 'never')

    - `sofort` ('auto' | 'always' | 'never')

    - `usBankAccount` ('auto' | 'always' | 'never')

  - `wallets` (object)
    By default, the Payment Element will display all the payment
methods that the underlying Checkout Session was created with.

However, wallets like Apple Pay and Google Pay are not payment
methods per the Checkout Session API. They will show when the
Checkout Session has the `card` payment method and the customer is
using a supported platform and have an active card in their
account.  This is the `auto` behavior, and it is the default for
choice for all wallets.

If you do not want to show a given wallet as a payment option, you
can set its property in `wallets` to `never`.

    - `applePay` ('auto' | 'never')

    - `googlePay` ('auto' | 'never')

    - `link` ('auto' | 'never')

### Create a Payment Element

```js
var element = checkout.createPaymentElement();
```

```es_next
const element = checkout.createPaymentElement();
```

## Create a Billing Address Element

This method creates an instance of a Billing Address Element.

This method returns the newly created Billing Address Element instance.

**Syntax:** `checkout.createBillingAddressElement(...)`

- `options` (object)
  Billing Address Element initialization options.

  - `contacts` (array)
    An array of [Contact](/js/appendix/contact_object.md) objects that can be displayed as saved addresses in the Billing Address Element. The first contact is automatically selected.

  - `display` (object)
    You can customize how certain fields are displayed.

    - `name` ('full' | 'split' | 'organization')
      By default, the Billing Address Element displays a full name field.
Specify 'split' to display a first name field and a last name field.
Specify 'organization' to display an organization field.

### Create a Billing Address Element

```js
var element = checkout.createBillingAddressElement();
```

```es_next
const element = checkout.createBillingAddressElement();
```

## Create a Shipping Address Element

This method creates an instance of a Shipping Address Element.

This method returns the newly created Shipping Address Element instance.

**Syntax:** `checkout.createShippingAddressElement(...)`

- `options` (object)
  Shipping Address Element initialization options.

  - `contacts` (array)
    An array of [Contact](/js/appendix/contact_object.md) objects that can be displayed as saved addresses in the Shipping Address Element. The first contact is automatically selected.

  - `display` (object)
    You can customize how certain fields are displayed.

    - `name` ('full' | 'split' | 'organization')
      By default, the Shipping Address Element displays a full name field.
Specify 'split' to display a first name field and a last name field.
Specify 'organization' to display an organization field.

### Create a Shipping Address Element

```js
var element = checkout.createShippingAddressElement();
```

```es_next
const element = checkout.createShippingAddressElement();
```

## Create an Express Checkout Element

This method creates an instance of an Express Checkout Element.

This method returns the newly created Express Checkout Element instance.

**Syntax:** `checkout.createExpressCheckoutElement(...)`

- `options` (object)
  Express Checkout Element initialization options.

  - `buttonHeight` (number)
    By default, the height of the buttons are 44px.

You can override this to specify a custom button height in the range of 40px-55px.

  - `buttonTheme` (object)
    Specify the preferred button theme to use. By default, Elements determines the themes based on the specified [appearance option](/js/elements_object/create.md#stripe_elements-options-appearance).

    - `applePay` ('black' | 'white' | 'white-outline')

    - `googlePay` ('black' | 'white')

    - `paypal` ('gold' | 'blue' | 'silver' | 'white' | 'black')

    - `klarna` ('dark' | 'light' | 'outlined')

  - `buttonType` (object)
    Specify the preferred button type to display.

    - `applePay` ('add-money' | 'book' | 'buy' | 'check-out' | 'contribute' | 'donate' | 'order' | 'plain' | 'reload' | 'rent' | 'subscribe' | 'support' | 'tip' | 'top-up')
      Default is `plain`.

    - `googlePay` ('book' | 'buy' | 'checkout' | 'donate' | 'order' | 'pay' | 'plain' | 'subscribe')
      Default is `buy`.

    - `paypal` ('paypal' | 'checkout' | 'buynow' | 'pay')
      Default is `paypal`.

    - `klarna` ('continue' | 'pay')
      Default is `pay`.

  - `layout` (object)
    Specify how the buttons are arranged in a grid-like layout in the Express Checkout Element.
Elements determines the layout by using certain factors, such as available space, number of buttons, and the defined `layout` object.

    - `maxColumns` (number)
      Defines the maximum number of columns the Express Checkout Element can use to render. Default is `0`, meaning unlimited.

    - `maxRows` (number)
      Defines the maximum number of rows the Express Checkout Element can use to render. Default is `0`, meaning unlimited.

    - `overflow` ('auto' | 'never')
      Specify whether or not to always hide the overflow menu or allow Elements to determine when to show the overflow menu. Default is `auto`.
You can't specify both `overflow: 'never'` and set `maxRows` to a number greater than 0.

  - `paymentMethodOrder` (array)
    By default, the Express Checkout Element uses a dynamic ordering that optimizes payment method display for each user.

You can override the default order in which payment methods display in the Express Checkout Element with a list of payment method types.

If there are payment methods that will show that are not specified in `paymentMethodOrder`, they display after the payment methods you specify. If you specify payment methods that will not show, they are ignored.

  - `paymentMethods` (object)
    Besides your Dashboard configuration, the availability of payment methods in the Express Checkout Element is influenced by the CheckoutSession configuration. By default, it displays all available payment methods based on both configurations. When setting the paymentMethods option, the Express Checkout Element merges your specified options with the default logic to determine the final set of payment methods displayed.

    - `amazonPay` ('auto' | 'never')

    - `applePay` ('always' | 'auto' | 'never')
      Apple Pay has additional configurations
that determine when Stripe can show it. By default, Apple Pay shows when the customer
is using a supported platform and when we determine it's advantageous for your conversion.
This is the `auto` behavior.
If you want to always show Apple Pay when the customer is using a supported platform,
you can set its property in `paymentMethods` to `always`.

    - `googlePay` ('always' | 'auto' | 'never')
      Google Pay has additional configurations
that determine when Stripe can show it. By default, Google Pay shows when the customer
is using a supported platform and when we determine it's advantageous for your conversion.
This is the `auto` behavior.
If you want to always show Google Pay when the customer is using a supported platform,
you can set its property in `paymentMethods` to `always`.

    - `link` ('auto' | 'never')

    - `paypal` ('auto' | 'never')

### Create an Express Checkout Element

```js
var element = checkout.createExpressCheckoutElement();
```

```es_next
const element = checkout.createExpressCheckoutElement();
```

## Create a Currency Selector Element

This method creates an instance of a Currency Selector Element.

This method returns the newly created Currency Selector Element instance.

**Syntax:** `checkout.createCurrencySelectorElement(...)`

### Create a Currency Selector Element

```js
var element = checkout.createCurrencySelectorElement();
```

```es_next
const element = checkout.createCurrencySelectorElement();
```

## Create a Tax ID Element

This method creates an instance of a Tax ID Element.

> This feature requires the `custom_checkout_tax_id_1` beta. To use it, pass `betas: ['custom_checkout_tax_id_1']` when initializing Stripe.js.

This method returns the newly created Tax ID Element instance.

**Syntax:** `checkout.createTaxIdElement(...)`

- `options` (object)
  Tax ID Element initialization options.

  - `visibility` ('always' | 'never' | 'auto')
    By default, the Tax ID Element displays when the user is in a country that supports tax ID collection.
Specify `always` to display the element regardless of the user's country.
Specify `never` to hide the element completely.

  - `fields` (object)
    By default, the Tax ID Element collects all tax ID information.

If it's not necessary for you to collect all fields, you can disable Tax ID Element collection of certain fields with the `fields` option.

    - `businessName` ('always' | 'never' | 'auto')
      Specify `always` to collect the business name.
Specify `never` to not collect the business name.
Default is `auto`.

  - `validation` (object)
    By default, the Tax ID Element will enforce preset validation for each field. You can customize the settings by using this option.

    - `businessName` (object)

      - `required` ('always' | 'never' | 'auto')
        Specify `always` to make business name a required field.
Specify `never` to make business name an optional field.
Default is `auto`.

    - `taxId` (object)

      - `required` ('always' | 'never' | 'auto')
        Specify `always` to make tax ID a required field.
Specify `never` to make tax ID an optional field.
Default is `auto`.

### Create a Tax ID Element

```js
var element = checkout.createTaxIdElement();
```

```es_next
const element = checkout.createTaxIdElement();
```

## Get the Payment Form Element

This method gets the previously created Payment Form Element instance, if it exists.

`getPaymentFormElement()` returns one of the following:
* The Payment Form Element instance.
* `null`, when no Payment Form Element has been created.

**Syntax:** `checkout.getPaymentFormElement(...)`

### Get the Payment Form Element

```js
var element = checkout.getPaymentFormElement();
```

```es_next
const element = checkout.getPaymentFormElement();
```

## Set the view on the Payment Form Element

Programmatically sets the active view on the Payment Form Element. This method is only available when `options[layout]` is `'compact'`.

The `viewIndex` parameter is a positive integer that corresponds to an index from the `views` array provided on the Element's [change event](/js/custom_checkout/element_events/on_change.md?type=paymentFormElement). You can only set a view where `enabled` is `true`.

`setView` returns a `Promise` that resolves when the view has been set. The `Promise` rejects with an `IntegrationError` if:
* The `viewIndex` is not a positive integer.
* The `viewIndex` exceeds the total views length provided on the Element's change event.
* The view at the specified index has `enabled: false`.
* The Element's `options[layout]` is `'expanded'`.

**Syntax:** `paymentFormElement.setView(...)`

- `viewIndex` (number) **required**
  A positive integer index corresponding to an entry in the `views` array provided on the Element's [change event](/js/custom_checkout/element_events/on_change.md?type=paymentFormElement). The view at the specified index must have `enabled: true`.

### Set the view on the Payment Form Element

```js
var paymentFormElement = checkout.createPaymentFormElement({ layout: 'compact' });
paymentFormElement.setView(1);
```

```es_next
const paymentFormElement = checkout.createPaymentFormElement({ layout: 'compact' });
paymentFormElement.setView(1);
```

## Get the Payment Element

This method gets the previously created Payment Element instance, if it exists.

`getPaymentElement()` returns one of the following:
* The Payment Element instance.
* `null`, when no Payment Element has been created.

**Syntax:** `checkout.getPaymentElement(...)`

### Get the Payment Element

```js
var element = checkout.getPaymentElement();
```

```es_next
const element = checkout.getPaymentElement();
```

## Get the Billing Address Element

This method gets the previously created Billing Address Element instance, if it exists.

`getBillingAddressElement()` returns one of the following:
* The Billing Address Element instance.
* `null`, when no Billing Address Element has been created.

**Syntax:** `checkout.getBillingAddressElement(...)`

### Get the Billing Address Element

```js
var element = checkout.getBillingAddressElement();
```

```es_next
const element = checkout.getBillingAddressElement();
```

## Get the Shipping Address Element

This method gets the previously created Shipping Address Element instance, if it exists.

`getShippingAddressElement()` returns one of the following:
* The Shipping Address Element instance.
* `null`, when no Shipping Address Element has been created.

**Syntax:** `checkout.getShippingAddressElement(...)`

### Get the Shipping Address Element

```js
var element = checkout.getShippingAddressElement();
```

```es_next
const element = checkout.getShippingAddressElement();
```

## Get the Express Checkout Element

This method gets the previously created Express Checkout Element instance, if it exists.

`getExpressCheckoutElement()` returns one of the following:
* The Express Checkout Element instance.
* `null`, when no Express Checkout Element has been created.

**Syntax:** `checkout.getExpressCheckoutElement(...)`

### Get the Express Checkout Address Element

```js
var element = checkout.getExpressCheckoutElement();
```

```es_next
const element = checkout.getExpressCheckoutElement();
```

## Get the Currency Selector Element

This method gets the previously created Currency Selector Element instance, if it exists.

`getCurrencySelectorElement()` returns one of the following:
* The Currency Selector Element instance.
* `null`, when no Currency Selector Element has been created.

**Syntax:** `checkout.getCurrencySelectorElement(...)`

### Get the Currency Selector Address Element

```js
var element = checkout.getCurrencySelectorElement();
```

```es_next
const element = checkout.getCurrencySelectorElement();
```

## Get the Tax ID Element

This method gets the previously created Tax ID Element instance, if it exists.

`getTaxIdElement()` returns one of the following:
* The Tax ID Element instance.
* `null`, when no Tax ID Element has been created.

**Syntax:** `checkout.getTaxIdElement(...)`

### Get the Tax ID Element

```js
var element = checkout.getTaxIdElement();
```

```es_next
const element = checkout.getTaxIdElement();
```

## Change the visual customization of Elements using the Appearance API

Change the visual customization of Elements created with Custom
Checkout using the [Appearance API](/elements/appearance-api.md)

**Syntax:** `checkout.changeAppearance(...)`

- `appearance` (object) **required**
  Match the design of your site with the [appearance option](/elements/appearance-api.md).
The layout of each Element stays consistent, but you can modify colors, fonts, borders, padding, and more.

### Change the visual customization of Elements

```js
checkout.changeAppearance({
  theme: 'night',
  labels: 'floating',
});
```

```es_next
checkout.changeAppearance({
  theme: 'night',
  labels: 'floating',
});
```

## Load additional custom fonts into Elements

Load an additional array of custom fonts into Elements after it loads.

**Syntax:** `checkout.loadFonts(...)`

- `fonts` (array) **required**
  An array of custom fonts.

Specify fonts as [CssFontSource](#css_font_source_object)
or [CustomFontSource](#custom_font_source_object) objects.

### Load additional custom fonts

```js
checkout.loadFonts([
  {
    cssSrc: "https://fonts.googleapis.com/css?family=Open+Sans",
  },
]);
```

```es_next
checkout.loadFonts([
  {
    cssSrc: "https://fonts.googleapis.com/css?family=Open+Sans",
  },
]);
```