> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React

> React SDK reference for Embedded Checkout component properties

## Properties

The Embedded Checkout component supports two modes of operation:

1. **New Order Mode**: Create orders client-side by passing `lineItems`, `recipient`, and other order details directly to the component.
2. **Existing Order Mode**: Use orders created server-side by passing `orderId` and `clientSecret` to the component.

<Note>
  Use **Existing Order Mode** when you need server-side order creation for enhanced security, custom business logic, or when integrating with the [Headless API](/payments/headless/overview).
</Note>

### Existing Order Properties

Use these properties when working with orders created server-side via the [Create Order API](/api-reference/headless/create-order).

<ResponseField name="orderId" type="string" id="order-id">
  The unique identifier of an existing order created via the server-side API. When provided, the checkout will load and process this existing order instead of creating a new one.

  ```tsx theme={null}
  <CrossmintEmbeddedCheckout
    orderId="order_abc123"
    clientSecret="secret_xyz789"
    payment={{
      crypto: { enabled: true },
      fiat: { enabled: true }
    }}
  />
  ```

  <Note>The `payment` object is still required when using existing orders to configure which payment methods are enabled in the checkout UI.</Note>

  <Warning>When using `orderId`, do not pass `lineItems`, `recipient`, or `locale` as these are already defined in the server-side order.</Warning>
</ResponseField>

<ResponseField name="clientSecret" type="string" id="client-secret">
  Secret token associated with the order for additional security. This is returned when creating an order via the server-side API.

  <Note>The `clientSecret` helps ensure that only authorized clients can access and complete the order.</Note>
</ResponseField>

### New Order Properties

Use these properties when creating orders directly in the client.

<ResponseField name="lineItems" type="object | array" required id="line-items">
  Specifies the assets to purchase. Can be a single item or array of items. Required when creating a new order (not used with `orderId`).

  <Accordion title="lineItems properties" id="line-items-props">
    <ResponseField name="collectionLocator" type="string" id="line-items-collection">
      Collection identifier in one of these formats:

      * `crossmint:<_YOUR_COLLECTION_ID_>[:_TEMPLATE_ID_]` - For collections created in Crossmint Console
        * Template ID is optional and requires template minting to be enabled
        * If template minting is disabled and a template ID is provided, the mint will select a template randomly
      * `<blockchain>:<contract-address>` - For collections using direct contract addresses (e.g., `polygon-amoy:0xF3d2d7b5666f579DcE385b2d53c54AB1b09Ef563`)

      <Note>
        When using template minting, append the templateId to the collection locator: `crossmint:collectionId:templateId`.
        Template minting must be enabled in the Crossmint Console or the mint will select a template randomly.
        See the [Mint to Specific Template guide](/payments/advanced/mint-to-specific-template) for details on enabling template minting and error handling.
      </Note>
    </ResponseField>

    <ResponseField name="tokenLocator" type="string" id="line-items-token">
      For secondary sales (buying existing assets). Token identifier in one of these formats:

      * EVM chains: `<blockchain>:<contractAddress>:<tokenId>`
      * Solana: `<blockchain>:<tokenAddress>`

      <Note>Using `tokenLocator` doesn't require registering the collection in Crossmint Console.</Note>

      <Warning>Use either `collectionLocator` (for primary sales) or `tokenLocator` (for secondary sales), not both.</Warning>
    </ResponseField>

    <ResponseField name="callData" type="object" id="line-items-calldata">
      Arguments passed to your contract's mint function:

      ```solidity Solidity theme={null}
      // Example mint function
      function mint(
        address to,  // Auto-filled by Crossmint
        uint256 quantity,
        uint256 totalPrice
      ) public payable {
        // ...
      }
      ```

      <Warning>Parameter names must match your contract's function arguments exactly.</Warning>

      <Check>Do not pass the recipient argument (e.g. `to`) in callData. Crossmint handles this automatically.</Check>
    </ResponseField>
  </Accordion>
</ResponseField>

<ResponseField name="recipient" type="object" id="recipient-config">
  Delivery details for the assets. You must specify either email OR wallet address, not both. Only used when creating new orders (not used with `orderId`).

  <Accordion title="recipient properties" id="recipient-props">
    <ResponseField name="email" type="string" id="recipient-email">
      Assets delivered to user's Crossmint wallet linked to this email
    </ResponseField>

    <ResponseField name="walletAddress" type="string" id="recipient-wallet">
      Assets delivered directly to this blockchain address
    </ResponseField>
  </Accordion>

  When not provided, user will be prompted during checkout.
</ResponseField>

<ResponseField name="locale" type="string" id="locale-config">
  Sets the checkout interface language. Only used when creating new orders (not used with `orderId`).

  `en-US` `de-DE` `es-ES` `fr-FR` `it-IT` `ja-JP` `ko-KR` `pt-PT` `ru-RU` `th-TH` `tr-TR` `uk-UA` `vi-VN` `zh-CN` `zh-TW` `Klingon`
</ResponseField>

### Common Properties

These properties can be used with both new orders and existing orders.

<ResponseField name="payment" type="object" required id="payment-config">
  Configuration for payment methods.

  <Accordion title="payment properties" id="payment-props">
    <ResponseField name="crypto" type="object" required id="payment-crypto">
      Crypto payment settings:

      ```tsx theme={null}
      {
        enabled: true,  // Enable/disable crypto payments
        defaultChain?: string, // Optional: e.g., "ethereum", "polygon", "solana"
        defaultCurrency?: string // Optional: e.g., "eth", "usdc"
      }
      ```

      <Note>
        For the complete list of supported chains, see [Supported Chains](/introduction/supported-chains).
      </Note>
    </ResponseField>

    <ResponseField name="fiat" type="object" required id="payment-fiat">
      Card & wallet payment settings:

      ```tsx theme={null}
      {
        enabled: true,  // Enable/disable fiat payments
        defaultCurrency?: string,  // Optional: e.g., "usd", "eur", "gbp"
        allowedMethods: {
          card: boolean,       // Credit/debit cards
          applePay: boolean,   // Apple Pay
          googlePay: boolean   // Google Pay
        }
      }
      ```

      <Note>
        Crossmint supports multiple fiat currencies. Contact our [support team](https://help.crossmint.com) for the complete list of available currencies.
      </Note>

      <Note>
        Embedded Checkout supports additional payment method customization. See our [Embedded Checkout payment methods guide](/payments/embedded/guides/payment-methods) for details.
      </Note>
    </ResponseField>

    <ResponseField name="receiptEmail" type="string" id="payment-receipt">
      Optional email address where purchase receipt will be sent
    </ResponseField>

    <ResponseField name="defaultMethod" type="string" id="payment-default">
      Sets the default payment tab: `fiat` or `crypto`
    </ResponseField>
  </Accordion>
</ResponseField>

<ResponseField name="appearance" id="embedded-appearance">
  Customization options for the checkout UI. See our [UI Customization guide](/payments/embedded/guides/ui-customization) for complete details.

  **Notable appearance options:**

  * Hide destination input: `rules.DestinationInput.display: "hidden"`
  * Hide receipt email input: `rules.ReceiptEmailInput.display: "hidden"`

  <Note>If inputs are hidden, you must provide the corresponding values via recipient/payment props.</Note>
</ResponseField>

## React Hooks

The following React hooks are available for use with the Embedded Checkout:

<ResponseField name="useCrossmintCheckout" type="function" id="use-crossmint-checkout">
  The `useCrossmintCheckout` hook is used to access the current order and checkout state.
</ResponseField>

<Note>
  All Crossmint hooks must be used within components wrapped by both `CrossmintProvider` and `CrossmintCheckoutProvider`:
</Note>

```tsx theme={null}
<CrossmintProvider apiKey="YOUR_API_KEY">
    <CrossmintCheckoutProvider>
        <YourComponent /> {/* Hooks can be used here */}
    </CrossmintCheckoutProvider>
</CrossmintProvider>
```

The following properties are available from the `useCrossmintCheckout` hook:

<ResponseField name="order" type="object">
  The current order object containing all order details including order ID, phase, line items, quote, and delivery information.

  ```tsx theme={null}
  const { order } = useCrossmintCheckout();
  ```

  For the complete Order object schema, see the [Get Order API reference](/api-reference/headless/get-order).

  To understand order phases and lifecycle, see the [Order Lifecycle guides](/payments/headless/guides/order-lifecycle/quote-phase).
</ResponseField>