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

# client.connect()

> Render the connect flow in your app.

Use `client.connect()` when you need to connect a customer's MoonPay account in
your app. The provider presents the connect flow in a full-screen native modal
with a slide animation and streams lifecycle events through `onEvent`.

If you want the full end-to-end flow (create session → check connection → connect), start with the [Connect a customer](/platform/guides/connect-a-customer) guide.

For UI recommendations, see [Presentation and appearance](/platform/guides/presentation-and-appearance).

```tsx Connect a customer focus={5-34} theme={null}
import {
  useMoonPay,
  type ConnectEvent,
} from "@moonpay/platform-sdk-react-native";

export function ConnectScreen() {
  const { client } = useMoonPay();

  const startConnect = async () => {
    const connectResult = await client.connect({
      onEvent: (event: ConnectEvent) => {
        switch (event.kind) {
          case "ready":
            // The UI is ready. Reveal the surface if you hid it while loading.
            break;
          case "complete":
            // event.payload is the Connection — same shape as client.getConnection() returns.
            if (event.payload.status === "active") {
              console.log(event.payload.customer.id);
            }
            break;
          case "error":
            // event.payload has a `code` discriminator. On validationError it carries
            // a list of field-level errors; on generic it may carry a developer message.
            console.error(event.payload);
            break;
        }
      },
    });

    if (!connectResult.ok) {
      // Handle error
      console.error(connectResult.error.message);
      return;
    }

    const connectFrame = connectResult.value;

    // You can dispose the frame at any time:
    // connectFrame.dispose();
  };

  // ...
}
```

***

## Parameters

| Field              | Type                            | Required | Description                                                                    |
| ------------------ | ------------------------------- | -------- | ------------------------------------------------------------------------------ |
| `theme`            | `object`                        |          | Optional appearance settings for the connect flow.                             |
| `theme.appearance` | `"dark"` \| `"light"`           |          | Force a specific appearance. If omitted, the frame uses the system appearance. |
| `onEvent`          | `(event: ConnectEvent) => void` |          | Callback invoked for connect flow events. See [`ConnectEvent`](#connectevent). |

The provider renders the connect frame in a full-screen modal automatically.
You don't need to pass a container.

### `ConnectEvent`

`onEvent` receives events as the connect flow progresses. Use `event.kind` to decide how to handle each event.

| kind         | Payload                                                                        | When you receive it                                                              |
| ------------ | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| `"ready"`    | —                                                                              | The connect UI is rendered and ready to be shown.                                |
| `"complete"` | [`Connection`](/platform/sdk-reference/react-native/get-connection#connection) | The customer completed the connect flow. Same shape as `client.getConnection()`. |
| `"error"`    | [`ConnectEventError`](#connecteventerror)                                      | The flow encountered an error.                                                   |

To remove the frame after the flow completes, call `connectFrame.dispose()` on the [`ConnectFrame`](#connectframe) returned from `client.connect()`.

#### `ConnectEventError`

The error event payload comes from the underlying connect frame. It is discriminated by `code`.

| Field     | Type                               | Required | Description                                                                                                                           |
| --------- | ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `code`    | `"validationError"` \| `"generic"` | ✅        | The error category.                                                                                                                   |
| `errors`  | `ConfigValidationFieldError[]`     |          | Present when `code` is `"validationError"`. Field-level errors describing which inputs (such as the session token) failed validation. |
| `message` | `string`                           |          | Present on `"generic"` errors. Developer-friendly details.                                                                            |

`ConfigValidationFieldError` entries have a `code` of `"invalidSessionToken"`, `"invalidClientToken"`, or `"invalidPublicKey"`, plus a developer-facing `message`.

```ts types.ts theme={null}
type ConfigValidationFieldError = {
  code: "invalidSessionToken" | "invalidClientToken" | "invalidPublicKey";
  message: string;
};

type ConnectEventError =
  | { code: "validationError"; errors: ConfigValidationFieldError[] }
  | { code: "generic"; message?: string };
```

## Result

`client.connect()` returns a `Result<ConnectFrame, ConnectError>`.

### Result envelope

`Result<ConnectFrame, ConnectError>`

| Field   | Type                            | Required | Description                      |
| ------- | ------------------------------- | -------- | -------------------------------- |
| `ok`    | `boolean`                       | ✅        | Whether the operation succeeded. |
| `value` | [`ConnectFrame`](#connectframe) |          | Present when `ok` is `true`.     |
| `error` | [`ConnectError`](#connecterror) |          | Present when `ok` is `false`.    |

### `ConnectFrame`

| Field     | Type         | Required | Description                                      |
| --------- | ------------ | -------- | ------------------------------------------------ |
| `dispose` | `() => void` | ✅        | Unmounts the frame and detaches event listeners. |

### `ConnectError`

`ConnectError` covers failures to mount the frame or complete the handshake,
and customer dismissal. Per-flow failures inside the frame surface with full
details through the `"error"` event payload,
[`ConnectEventError`](#connecteventerror); the method then resolves with a
generic `ConnectError`.

| Field     | Type     | Required | Description                                                                                                                                               |
| --------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message` | `string` | ✅        | A developer-friendly description of the failure. `"Connect flow dismissed"` when the customer closes the modal before completing (including mid-loading). |

```ts types.ts theme={null}
type ConnectFrame = {
  dispose: () => void;
};

type ConnectError = {
  message: string;
};
```

## Resources

For full protocol details, see the [connect frame reference](/platform/frames/connect).