diff --git a/site/docs/pages/config/onchainkit-provider.mdx b/site/docs/pages/config/onchainkit-provider.mdx
index da9bde8472..7fa749cf49 100644
--- a/site/docs/pages/config/onchainkit-provider.mdx
+++ b/site/docs/pages/config/onchainkit-provider.mdx
@@ -38,7 +38,7 @@ const App = () => {
| [`apiKey`](#apikey) | Client API Key from Coinbase Developer Platform. | No |
| [`rpcUrl`](#rpc-url) | RPC URL for onchain requests. | No |
| [`projectId`](#project-id) | Your Coinbase Developer Platform Project ID. | No |
-| [`config`](#config) | - `config.appearance` — customized your OnchainKit project's appearance
- `config.paymaster` — Paymaster URL for gas sponsorship | No |
+| [`config`](#config) | - `config.appearance` — Customize your OnchainKit project's appearance
- `config.paymaster` — Paymaster URL for gas sponsorship
- `config.wallet` — Wallet configuration options | No |
| [`schemaId`](#schema-id) | _[Deprecation Pending]_ The schema ID for attestations from the Ethereum Attestation Service (EAS). | No |
| [`address`](#address) | _[Deprecation Pending]_ This prop is no longer used. | No |
@@ -109,7 +109,7 @@ You can obtain a Project ID from the [Coinbase Developer Platform](https://porta
`config` is an object that can be used to customize the appearance and behavior
of the OnchainKit components.
-This prop has two keys: `appearance` and `paymaster`.
+This prop has three keys: `appearance`, `paymaster`, and `wallet`.
#### Appearance
@@ -129,6 +129,16 @@ Explore appearance options in the [OnchainKit Playground](https://onchainkit.xyz
You can configure your Paymaster and obtain your Paymaster URL from the
[Coinbase Developer Platform](https://portal.cdp.coinbase.com/products/bundler-and-paymaster).
+#### Wallet
+
+`wallet` configures the wallet connection experience and has the following properties:
+
+- `display` — The display mode for the wallet interface. Can be either:
+ - `'modal'` — Shows wallet connection in a modal overlay with wallet aggregation
+ - `'classic'` — Shows wallet connection in the traditional inline style
+- `termsUrl` — URL to your terms of service
+- `privacyUrl` — URL to your privacy policy
+
---
### Address _[Deprecation Pending]_
diff --git a/site/docs/pages/wallet/wallet.mdx b/site/docs/pages/wallet/wallet.mdx
index 236c0d6c0c..5b46039804 100644
--- a/site/docs/pages/wallet/wallet.mdx
+++ b/site/docs/pages/wallet/wallet.mdx
@@ -236,7 +236,9 @@ import {
-### Customize Connect button text and style
+::::
+
+## Customize Connect button text and style
Each OnchainKit component offers the flexibility to customize `className`
and adjust the style of the React components it represents.
@@ -317,49 +319,23 @@ import { color } from '@coinbase/onchainkit/theme';
-### Implementing the Wallet Modal for wallet connection aggregation
+## Using Wallet Modal
+
+
-OnchainKit provides a built-in wallet modal that offers users multiple connection options. The modal automatically appears when users click the `ConnectWallet` component and provides three distinct connection paths:
+Wallet modal offers users multiple wallet connection options. The modal automatically appears when users click the `ConnectWallet` component and provides three distinct connection paths:
1. Quickly create a new smart wallet for new users
2. Coinbase Wallet connection (supporting both smart wallets and EOA)
-3. Other wallets via WalletConnect
+3. Other wallets via [WalletConnect](https://docs.walletconnect.org/)
-#### Setup Steps
+### Setup Steps
-1. Configure the wallet connectors in your Wagmi config:
-
-```tsx [wagmiConfig.ts]
-const wagmiConfig = createConfig({
- chains: [base, baseSepolia],
- connectors: [
- // Smart wallet support
- coinbaseWallet({
- appName: 'Your App',
- preference: 'smartWalletOnly',
- }),
- // EOA wallet support
- coinbaseWallet({
- appName: 'Your App',
- preference: 'eoaOnly',
- }),
- // Other wallets via WalletConnect
- walletConnect({ // [!code focus]
- projectId: process.env.WALLET_CONNECT_PROJECT_ID, // [!code focus]
- showQrModal: true, // [!code focus]
- metadata: { // [!code focus]
- name: 'Your App', // [!code focus]
- description: 'Your app description', // [!code focus]
- url: 'https://your-app.com', // [!code focus]
- icons: [], // [!code focus]
- },
- }),
- ],
- // ... other config
-});
-```
+::::steps
-2. Configure the `OnchainKitProvider` with modal settings:
+## Configure the `OnchainKitProvider` with modal settings:
```tsx [providers.tsx]
```
-3. Use the `ConnectWallet` component in your UI:
+## Use the `ConnectWallet` component in your UI:
```tsx [App.tsx]
@@ -429,9 +405,11 @@ const wagmiConfig = createConfig({
-## Examples
+::::
+
+## Example usage
-### With Sign In With Ethereum (SIWE)
+### Usage with Sign In With Ethereum (SIWE)
To use [Sign In With Ethereum (SIWE)](https://docs.login.xyz/general-information/siwe-overview) with OnchainKit, you can use the `onConnect` prop in the `` component. This will trigger the SIWE prompt when the user connects their wallet.
@@ -466,6 +444,7 @@ The components are designed to work together hierarchically. For each component,
- `` - Serves as the main container for all wallet-related components.
- `` - Handles the wallet connection process. Place child components inside to customize the connect button appearance.
+- `` - Enables a wallet aggregation experience.
- `` - Contains additional wallet information and options. Place inside the `` component.
- `` - Displays user identity information. Place inside `` for a complete profile view.
- `` - Displays the user's Basename within the dropdown.
diff --git a/site/docs/public/assets/wallet-modal.gif b/site/docs/public/assets/wallet-modal.gif
new file mode 100644
index 0000000000..29188c695e
Binary files /dev/null and b/site/docs/public/assets/wallet-modal.gif differ