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

# Modal

> Pre-built React deposit UI

The Daimo modal is a drop-in React component that handles the entire deposit flow: chain selection, wallet connection, transaction signing, and status updates.

## Installation

```bash theme={null}
npm install @daimo/sdk
```

Peer dependencies: `react >= 18`.

## Setup

Wrap your app in `DaimoSDKProvider`:

```tsx theme={null}
import { DaimoSDKProvider } from "@daimo/sdk/web";
import "@daimo/sdk/web/theme.css";

function App() {
  return <DaimoSDKProvider>{/* your app */}</DaimoSDKProvider>;
}
```

## Basic usage

1. Create a session on your server (see [Quickstart](/quickstart))
2. Pass `sessionId` and `clientSecret` to `<DaimoModal>`

```tsx theme={null}
import { DaimoModal } from "@daimo/sdk/web";

function DepositPage({ sessionId, clientSecret }) {
  return (
    <DaimoModal
      sessionId={sessionId}
      clientSecret={clientSecret}
      onPaymentStarted={() => console.log("deposit initiated")}
      onPaymentCompleted={() => console.log("deposit succeeded")}
    />
  );
}
```

The `sessionId` and `clientSecret` come from the session object returned by `POST /v1/sessions`.

## Props

| Prop                       | Type      | Default | Description                                                                                                                                                |
| -------------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sessionId`                | `string`  | -       | Unique session ID. Sessions are created server-side. (required)                                                                                            |
| `clientSecret`             | `string`  | -       | Unique client secret, returned at session creation. (required)                                                                                             |
| `defaultOpen`              | `boolean` | `true`  | Whether the modal starts open                                                                                                                              |
| `connectToInjectedWallets` | `boolean` | `false` | Skip payment method picker. Auto-connect to injected wallets.                                                                                              |
| `connectToAddress`         | `Address` | -       | Skip payment method picker. Use already-connected EVM wallet at the specified address.                                                                     |
| `embedded`                 | `boolean` | `false` | Render inline instead of as a floating modal                                                                                                               |
| `platform`                 | `string`  | auto    | Caller's platform. Prefer `"desktop"` or `"mobile"`; legacy `"ios"`, `"android"`, and `"other"` still work. Affects wallet and exchange UX. Auto-detected. |
| `returnUrl`                | `string`  | -       | URL to navigate to after successful payment                                                                                                                |
| `returnLabel`              | `string`  | -       | Text shown on successful payment. Button label if `returnUrl` is set (default "Return to App"), otherwise text.                                            |

## Event handlers

| Handler              | Fires when                             |
| -------------------- | -------------------------------------- |
| `onPaymentStarted`   | User's deposit transaction is detected |
| `onPaymentCompleted` | Funds are delivered to the destination |
| `onOpen`             | Modal becomes visible                  |
| `onClose`            | Modal is dismissed                     |

## Embedded mode

Set `embedded` to render the deposit flow inline instead of as an overlay modal:

```tsx theme={null}
<DaimoModal
  sessionId={sessionId}
  clientSecret={clientSecret}
  embedded
  onPaymentCompleted={() => router.push("/success")}
/>
```

This is useful for embedding the deposit flow directly into a page layout.

## Customization

Set your org theme in the Daimo dashboard to match the modal to your brand. The modal SDK loads it automatically from the session.

See [Customization](/guides/customization) for the dashboard flow, token list, and per-session CSS override.