# Openfort UI Configuration

<OpenfortConfigDemo />

:::info
If using Next.js App Router, add `"use client"` at the top of any file that imports OpenfortProvider, OpenfortButton, or Openfort hooks.
:::

:::tip\[Try it live]
The preview boxes throughout this page run a real Openfort wallet on Base. Log in through any one of them and the rest stay logged in — once connected, each box opens that exact wallet screen. The label in each box is the hook or component that opens it.
:::

This page covers the `uiConfig` options that control **what the wallet does** — authentication, recovery, funding, disclaimers, and behavior. For **how it looks** (theme, colors, fonts, logo, layout, and visual toggles), see [Customization](/docs/products/embedded-wallet/react/ui/customization).

For wallet setup (`walletConfig`), see [Wallet configuration](/docs/products/embedded-wallet/react/wallet).

## Auth Providers

<DemoBox action="auth" />

The `authProviders` property is an array of `AuthProvider` authentication providers.
Currently, the following providers are supported:

### Social providers

* `AuthProvider.GOOGLE`
* `AuthProvider.FACEBOOK`
* `AuthProvider.TWITTER`
* `AuthProvider.DISCORD`
* `AuthProvider.APPLE`

### Email and phone providers

* `AuthProvider.EMAIL_PASSWORD` - Email with password authentication
* `AuthProvider.EMAIL_OTP` - Email with OTP (passwordless) authentication
* `AuthProvider.PHONE` - Phone number with SMS OTP authentication

### Other providers

* `AuthProvider.GUEST` - Anonymous guest authentication
* `AuthProvider.WALLET` - External wallet (SIWE) authentication. Ethereum only, requires [wagmi setup](/docs/products/embedded-wallet/react/hooks/useWalletAuth).

Example configuration:

```tsx
import { OpenfortProvider, AuthProvider } from '@openfort/react'

function App() {
  return (
    <OpenfortProvider
      publishableKey="YOUR_OPENFORT_PUBLISHABLE_KEY"
      // ... other configuration

      uiConfig={{ // [!code focus]
        authProviders: [ // [!code focus]
          AuthProvider.GUEST, // [!code focus]
          AuthProvider.EMAIL_PASSWORD, // [!code focus]
          AuthProvider.EMAIL_OTP, // [!code focus]
          AuthProvider.PHONE, // [!code focus]
          AuthProvider.GOOGLE, // [!code focus]
          AuthProvider.WALLET, // [!code focus]
        ], // [!code focus]
      }} // [!code focus]
    >
      {/* Add your wallet components here */}
    </OpenfortProvider>
  )
}
```

:::note
Social login configuration - Social login like Google, Facebook, and Twitter require some additional configuration to let Openfort know about your app. You can find more information in the [Social login](/docs/configuration/social-login) guide.
:::

Other authentication options:

| Option | What it does |
| --- | --- |
| `authProvidersLength` | How many providers to show before collapsing the rest into "more". |
| `skipEmailVerification` | Skip the email verification step. |
| `phoneConfig` | Default country, preferred countries, and formatting for phone auth. |

## Wallet recovery methods

Configure the wallet recovery methods available to your users. By default, all recovery methods are enabled.

If you configure automatic recovery in the `OpenfortProvider` (view the [wallet recovery](/docs/products/embedded-wallet/react/wallet#wallet-recovery) guide), it will be used as the default recovery method when creating a wallet.

You can set the **default method** and the **available methods** with the `walletRecovery` property:

```tsx
import { OpenfortProvider, RecoveryMethod } from '@openfort/react'

function App() {
  return (
    <OpenfortProvider
      publishableKey="YOUR_OPENFORT_PUBLISHABLE_KEY"
      // ... other configuration

      uiConfig={{ // [!code focus]
        walletRecovery:{ // [!code focus]
          defaultMethod: RecoveryMethod.PASSKEY, // [!code focus]
          allowedMethods: [ // [!code focus]
            RecoveryMethod.PASSWORD, // [!code focus]
            RecoveryMethod.AUTOMATIC, // [!code focus]
            RecoveryMethod.PASSKEY], // [!code focus]
        }, // [!code focus]
      }} // [!code focus]
    >
      {/* Add your wallet components here */}
    </OpenfortProvider>
  )
}
```

The available recovery methods are shown to the user when they create their wallet.

:::info
`RecoveryMethod.AUTOMATIC` is automatically removed from `allowedMethods` if no encryption session configuration (`createEncryptedSessionEndpoint` or `getEncryptionSession`) is provided in `walletConfig`.
:::

## Link wallet on sign up

By default, when a user signs up using social login or email authentication, a new wallet is created for them.

You can change this behavior for the user to connect their wallet instead of creating a new one by changing the `linkWalletOnSignUp` property.

:::info
`linkWalletOnSignUp` connects an external Ethereum wallet via SIWE. This option is only relevant when using [wagmi setup](/docs/products/embedded-wallet/react/hooks/useWalletAuth) with an Ethereum configuration.
:::

* `LinkWalletOnSignUpOption.OPTIONAL`: The user can choose to link their wallet or create an embedded one.
* `LinkWalletOnSignUpOption.REQUIRED`: The user must link their wallet.
* `LinkWalletOnSignUpOption.DISABLED`: **(default)** The user always creates a new wallet.

## Disclaimer

There are two ways to configure the disclaimer, you can either set the terms of service and privacy policy URLs:

* `privacyPolicyUrl`: The privacy policy URL.
* `termsOfServiceUrl`: The terms of service URL.

or customize the disclaimer component:

* `disclaimer`: A disclaimer to be shown in the wallet.

## Send

<DemoBox action="send" />

The **Send** screen lets users transfer assets from their embedded wallet to any address. Gas is sponsored when a paymaster is configured. Open the full flow with `useUI().openSend()`, or pass a prepared transaction — `useUI().openSend({ to, amount, asset })` — to jump straight to the confirmation (approval) screen, as the demo above does.

## Receive

<DemoBox action="receive" />

The **Receive** screen shows the wallet's address and a QR code so others can pay it. Open it with `useUI().openReceive()`.

:::info
Receive is for **same-chain** transfers — funds must be sent on the wallet's own chain. For cross-chain top-ups (pay from any chain, token, or exchange), use [Funding](#funding) instead.
:::

## Sign message

<DemoBox action="signMessage" />

<DemoBox action="signTypedData" />

Prompt the user to sign a message or EIP-712 typed data with a confirmation screen, via [`useSignMessage`](/docs/products/embedded-wallet/react/wallet/actions/sign-message). Signing is gasless — no transaction. Open with `useSignMessage().signMessage(text)` or `signTypedData(typedData)`.

## Funding

<DemoBox action="funding" />

The wallet modal includes a **Deposit** flow that lets users top up their wallet from any chain, token, or exchange — see [Funding](/docs/configuration/funding) for the concept.

The destination is the active wallet's address, resolved from the target chain's family: an EVM `targetChain` settles into the EVM wallet, a Solana `targetChain` into the Solana wallet. Override the destination chain/token and tune the pickers:

```tsx
import { OpenfortProvider } from '@openfort/react'

<OpenfortProvider
  publishableKey="pk_…"
  uiConfig={{ // [!code focus]
    funding: { // [!code focus]
      targetChain: 'eip155:137', // deposits land on Polygon… // [!code focus]
      targetCurrency: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359', // …as USDC // [!code focus]
    }, // [!code focus]
  }} // [!code focus]
>
```

The Deposit hub shows up to five methods:

* **Transfer from wallet** — on mobile, one-tap deeplinks into the user's wallet app (MetaMask, Coinbase Wallet, Phantom, Trust, Rainbow, Rabby) that open a prefilled [deposit send page](/docs/configuration/funding#hosted-deposit-page); on desktop, a direct transfer through the connected browser-extension wallet.
* **Transfer from address** — a cross-chain deposit address with a QR; send from any chain.
* **Transfer from exchange** — Coinbase direct transfer, delivering to the destination on a supported chain. Binance is coming soon.
* **Onramp with Card** — fiat on-ramp.

### Choosing which methods show

By default the hub shows every available method (Apple Pay first on mobile). Use `funding.methods` to pick which appear and in what order — the same pattern as `authProviders` for the auth modal.

```tsx
import { OpenfortProvider, FundingMethod } from '@openfort/react'

<OpenfortProvider
  publishableKey="pk_…"
  uiConfig={{
    funding: {
      // Only these, in this order — e.g. crypto-only, no fiat.
      methods: [FundingMethod.WALLET, FundingMethod.ADDRESS, FundingMethod.EXCHANGE],
    },
  }}
>
```

`FundingMethod` values: `APPLE_PAY`, `CARD`, `WALLET` (Transfer from wallet), `ADDRESS` (Transfer from address), `EXCHANGE` (Transfer from exchange). Device, region, and availability gating still apply — Apple Pay stays mobile-only, and the cross-chain rails are hidden until the funding backend is reachable.

### Choosing source chains & currencies

The chains and currencies inside the crypto/exchange pickers aren't hardcoded — they're fetched live from the rail. By default the modal shows a curated subset; narrow it further with `sourceChains` (a CAIP-2 allowlist, also the order) and `sourceCurrencies` (a symbol allowlist where the `'native'` sentinel matches each chain's native asset — ETH, SOL, POL…).

```tsx
<OpenfortProvider
  publishableKey="pk_…"
  uiConfig={{
    funding: {
      sourceChains: ['eip155:8453', 'eip155:42161', 'eip155:137'],
      sourceCurrencies: ['native', 'USDC', 'USDT'],
    },
  }}
>
```

Defaults when omitted: chains `Arbitrum, Base, BNB, Ethereum, Optimism, Polygon, Solana`; currencies `['native', 'USDC', 'USDT']`. A selection is shown only if the rail can route it — a chain or currency the rail doesn't support (e.g. a non-bridgeable native asset) is silently skipped, so you never offer a route that would fail.

### Funding reference

Everything the Deposit hub reads from `uiConfig`. `fundingBaseUrl` sits at the top level; the rest live under `funding`.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `fundingBaseUrl` | `string` | SDK backend (`https://api.openfort.io`) | Base URL of the funding **JSON API** (serves `/v2/funding/*` — chains + sessions). Defaults to the SDK backend; set only to point the crypto/exchange rails at a custom funding service. Distinct from `funding.depositPageUrl` (the hosted deposit *page*). |
| `funding.targetChain` | `string` (CAIP-2) | `eip155:8453` (Base) | Chain deposits settle on. |
| `funding.targetCurrency` | `string` (address) | USDC on Base | Token deposits settle as (zero address for native). |
| `funding.methods` | `FundingMethod[]` | all (Apple Pay first on mobile) | Which methods show, and in what order. |
| `funding.sourceChains` | `string[]` (CAIP-2) | curated set above | Allowlist (and order) of source chains in the pickers. |
| `funding.sourceCurrencies` | `string[]` | `['native', 'USDC', 'USDT']` | Allowlist of source currencies; `'native'` matches each chain's native asset. |
| `funding.depositPageUrl` | `string` | `https://deposit.openfort.io` | URL of the [hosted deposit page](/docs/configuration/funding#hosted-deposit-page) the mobile "Transfer from wallet" deeplinks open. |

For a custom Deposit UI driven by a hook instead of the modal, see [Funding with `useFunding`](/docs/products/embedded-wallet/react/wallet/funding).

### Onramp with cards

Apple Pay and Card are fiat on-ramps surfaced inside the Deposit hub. Configure where they point:

<DemoBox action="buy" />

| Option | What it does |
| --- | --- |
| `buyWithCardUrl` | URL for the buy-with-card flow. |
| `buyFromExchangeUrl` | URL for the buy-from-exchange flow. |
| `buyTroubleshootingUrl` | URL for buy troubleshooting help. |

## Export key

Your users are able to export the embedded wallet private key by using export key method.

<DemoBox action="export" />

## WalletConnect

| Option | What it does |
| --- | --- |
| `appName` | App name shown in WalletConnect and the modal header. |
| `walletConnectCTA` | Show the WalletConnect CTA as a `link`, `modal`, or `both`. |
| `walletConnectName` | Name used for WalletConnect. |

## Onboarding & help

| Option | What it does |
| --- | --- |
| `ethereumOnboardingUrl` | Custom URL for the Ethereum onboarding flow. |
| `walletOnboardingUrl` | Custom URL for the wallet onboarding flow. |
| `hideQuestionMarkCTA` | Hide the help question-mark icon. |
| `hideNoWalletCTA` | Hide the "no wallet" call-to-action. |
| `disableSiweRedirect` | Disable the redirect to the SIWE page after a wallet connects. |

## Advanced

| Option | What it does |
| --- | --- |
| `language` | UI language. |
| `bufferPolyfill` | Polyfill the Node.js `Buffer` API for browsers. Default `true`; set `false` if your bundler already provides it. |

:::tip\[Looking for appearance options?]
Theme, mode, colors, fonts, logo, custom avatar, custom pages, and visual toggles (`hideBalance`, `hideTooltips`, `reducedMotion`, …) live on the [Customization](/docs/products/embedded-wallet/react/ui/customization) page.
:::

### Debug mode

Pass `true` to enable all debug logging, or an object for granular control:

| Flag | What it logs |
|------|-------------|
| `openfortReactDebugMode` | React SDK state transitions and hook lifecycle |
| `openfortCoreDebugMode` | Core JS SDK operations (auth, signing) |
| `shieldDebugMode` | Shield (key management) operations |
| `debugRoutes` | Modal route navigation |

```tsx
<OpenfortProvider
  publishableKey="pk_..."
  debugMode={{                       // [!code focus]
    openfortReactDebugMode: true,    // [!code focus]
    openfortCoreDebugMode: false,    // [!code focus]
    shieldDebugMode: true,           // [!code focus]
  }}                                 // [!code focus]
>
```