> ## 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 UI.

Use `client.connect()` when you need to connect a customer's MoonPay account in your app. This method mounts the co-branded connect flow into your UI 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).

```ts Connect a customer focus={6-31} theme={null}
import { createClient, type ConnectEvent } from "@moonpay/platform-sdk-web";

const client = createClient({ sessionToken: "c3N0XzAwMQ==" });

const connectResult = await client.connect({
  container: document.querySelector("#connectContainer"),
  onEvent: (event: ConnectEvent) => {
    switch (event.kind) {
      case "ready":
        // The UI is ready. Reveal the container if you hide 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;

// Remove the frame from the DOM now that the flow has completed:
// connectFrame.dispose();
```

<Callout icon="circle-info" iconType="regular">
  The promise returned by `client.connect()` resolves after the customer
  completes the connect flow (or an error ends it). Track flow progress —
  including the moment the UI is ready to show — through `onEvent`, not by
  awaiting the promise.
</Callout>

***

## Parameters

| Field              | Type                            | Required | Description                                                                                                                    |
| ------------------ | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `container`        | `HTMLElement`                   | ✅        | A [connected](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected) DOM element to render the connect frame into. |
| `theme`            | `object`                        |          | Optional appearance settings for the connect flow.                                                                             |
| `theme.appearance` | `"dark"` \| `"light"`           |          | Force a specific appearance. If omitted, the frame uses the user's system appearance.                                          |
| `onEvent`          | `(event: ConnectEvent) => void` |          | Callback invoked for connect flow events. See [`ConnectEvent`](#connectevent).                                                 |

### `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/web/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 from the DOM after the flow completes, call `connectFrame.dispose()` on the [`ConnectFrame`](#connectframe) returned from `client.connect()`. The frame handle only becomes available once the flow completes — the returned promise stays pending while the customer works through the flow.

#### `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` | ✅        | Removes the frame from the DOM and detaches event listeners. |

### `ConnectError`

`ConnectError` covers failures to mount the frame or complete the handshake. Per-flow failures inside the frame surface through the `"error"` event payload, [`ConnectEventError`](#connecteventerror).

| Field     | Type     | Required | Description                                                                         |
| --------- | -------- | -------- | ----------------------------------------------------------------------------------- |
| `message` | `string` | ✅        | A developer-friendly description of the failure (for example, a handshake timeout). |

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