## PaymentElement

Use the `PaymentElement` from `@stripe/react-stripe-js/checkout`
to collect payment details for more than [40 payment methods](/docs/payments/payment-methods/integration-options.md) from around the globe.

The component must be rendered inside a [CheckoutProvider](/js/react_stripe_js/checkout/checkout_provider.md).

### Props

- `id` (string)
  Sets the DOM `id` attribute on the rendered Element container. Use this to
target the Element for styling or testing.

- `className` (string)
  Applies custom CSS classes to the Element container.

- `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')

- `onChange` (function)
  Callback called when any value in the [change event payload](/js/element/events/on_change?type=paymentElement.md#element_on_change-handler) changes.

- `onReady` (function)
  Callback called once the Element is fully rendered.
Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler).

- `onBlur` (function)
  Callback called when the Element loses focus.

- `onFocus` (function)
  Callback called when the Element receives focus.

- `onEscape` (function)
  Callback called when the escape key is pressed within the Element.

- `onLoaderStart` (function)
  Callback called right before Stripe displays the Element skeleton loader.
Receives the Element instance as its only argument.

- `onLoadError` (function)
  Callback called when the Element fails to load.

### Render PaymentElement

```jsx
import React from 'react';
import {CheckoutProvider, PaymentElement} from '@stripe/react-stripe-js/checkout';
import {loadStripe} from '@stripe/stripe-js';

const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}');

const App = ({clientSecret}) => (
  <CheckoutProvider
    stripe={stripePromise}
    options={{clientSecret}}
  >
    <form>
      <PaymentElement />
      <button type="submit">Pay now</button>
    </form>
  </CheckoutProvider>
);

export default App;
```