## CheckoutForm

> This feature is in public preview. See [Embedded form](https://docs.stripe.com/payments/checkout/how-checkout-works.md?payment-ui=checkout-form) for more information.

Use the `CheckoutForm` from `@stripe/react-stripe-js/checkout` to render the embedded form; a single form that handles payment, address, and other elements.

The component must be rendered inside a [CheckoutFormProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_form_provider.md).

### Props

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

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

- `options`
  Embedded form initialization options.
    - `layout`
      The layout of the embedded form. The `'expanded'` layout is a single-step embedded form, while the `'compact'` layout is a multi-step embedded form. When you leave this undefined, Stripe renders the layout it determines has the best conversion.

The `'compact'` layout is in private preview. [Request access](https://docs.stripe.com/checkout/form/quickstart.md#request-access-to-the-compact-layout).
    - `contacts`
      An array of objects that you can use to display saved addresses in the embedded form. The first contact is automatically selected.
      - `name`
        The name of the contact. This might be a person, or a business name.
      - `address`
        The address of the contact.
        - `line1`
        - `line2`
        - `city`
          The name of a city, town, village, etc.
        - `state`
          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.
        - `postal_code`
          The postal code or ZIP code, also known as PIN code in India.
        - `country`
          Two-letter country code, capitalized. Valid two-letter country codes are specified by ISO3166 alpha-2.
      - `phone`
        The phone number of the contact.
    - `features`
      Configuration for client-side features of the embedded form, such as amount summary expansion and promotion code collection.
      - `amountSummary`
        Configuration for the amount summary in the embedded form.
        - `expanded`
          Controls whether the amount summary can be collapsed in the embedded form.

By default (`'auto'`), the amount summary starts collapsed when it has expandable content, and the customer can expand or collapse it.

Set to `'always'` to keep the amount summary expanded and prevent it from being collapsed.

If there are no additional details to display, the summary shows only the total and doesn't expand, regardless of this setting.
      - `promotionCodeCollection`
        Controls whether to show promotion code input in the embedded form. Defaults to `'auto'`.

- `'auto'`: Shows the promotion code input if the Checkout Session enables [allow_promotion_codes](https://docs.stripe.com/api/checkout/sessions/create#create_checkout_session-allow_promotion_codes).
- `'never'`: Never shows the promotion code input in the embedded form. Use this if you build your own promotion code input outside of the form.
    - `expressCheckout`
      Express checkout configuration options.
      - `buttonHeight`
        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`
        Specify the preferred button theme to use. By default, Elements determines the themes based on the specified [appearance option](https://docs.stripe.com/js/elements_object/create.md#stripe_elements-options-appearance).
        - `applePay`
        - `googlePay`
        - `paypal`
        - `klarna`
      - `paymentMethods`
        In addition to your Dashboard configuration, the CheckoutSession configuration also influences the availability of payment methods in the Embedded form. By default, it displays all available payment methods based on both configurations. When setting the paymentMethods option, the Embedded form merges your specified options with the default logic to determine the final set of payment methods displayed.
        - `amazonPay`
        - `applePay`
          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`.

Apple Pay on non-Safari desktop browsers is only supported when its property in `paymentMethods` is set to `always`.
        - `googlePay`
          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`
        - `paypal`

- `onChange`
  Callback called when any value in the [change event payload](https://docs.stripe.com/js/custom_checkout/element_events/on_change.md?type=checkoutForm) changes.

- `onConfirm`
  Triggered when the embedded form sends a [confirm event](https://docs.stripe.com/js/custom_checkout/element_events/on_confirm.md?type=checkoutForm). Use this to handle payment confirmation.

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

- `onBlur`
  Callback called when the Element loses focus.

- `onFocus`
  Callback called when the Element receives focus.

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

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

### Example

```title
Render CheckoutForm
```