Integration Examples

OpenOcean Widget Integration Guide

This guide provides step-by-step instructions for integrating OpenOcean Widget into different frameworks and setups.

Table of Contents

• Vite + React

• Next.js (App Router)

• Next.js (Pages Router)

• Vue 3

• Nuxt 3

• Svelte

• Remix

• RainbowKit

• ConnectKit

• Privy

• Privy + Ethers

• Reown (WalletConnect)

• Dynamic

• Zustand Widget Config

• Deposit Flow

---

Vite + React

Installation

npm install @openocean.finance/widget @openocean.finance/wallet-management
npm install @tanstack/react-query wagmi viem
npm install --save-dev vite-plugin-node-polyfills

Configuration

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { nodePolyfills } from 'vite-plugin-node-polyfills'

export default defineConfig({
  plugins: [
    react(),
    nodePolyfills({
      include: ['buffer', 'process'],
    }),
  ],
})

Usage

src/App.tsx

import { OpenOceanWidget } from '@openocean.finance/widget'

export function App() {
  return (
    <OpenOceanWidget
      integrator="vite-example"
      config={{
        buildUrl: false,
        subvariant: 'split',
        theme: {
          container: {
            border: '1px solid rgb(234, 234, 234)',
            borderRadius: '16px',
          },
        },
      }}
    />
  )
}

Key Points

• Requires vite-plugin-node-polyfills for Node.js polyfills

• Basic React integration without wallet management

• Can be extended with wallet providers

---

Next.js (App Router)

Installation

npm install @openocean.finance/widget @openocean.finance/widget-sdk
npm install @mui/material-nextjs

Configuration

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@openocean.finance/widget'],
}

module.exports = nextConfig

Usage

app/page.tsx

import { Widget } from '@/components/Widget'

export default function Home() {
  return (
    <main>
      <Widget />
    </main>
  )
}

components/Widget.tsx

'use client'

import type { WidgetConfig } from '@openocean.finance/widget'
import { OpenOceanWidget, WidgetSkeleton } from '@openocean.finance/widget'
import { ClientOnly } from './ClientOnly'

export function Widget() {
  const config = {
    appearance: 'light',
    theme: {
      container: {
        border: '1px solid rgb(234, 234, 234)',
        borderRadius: '16px',
      },
    },
  } as Partial<WidgetConfig>

  return (
    <ClientOnly fallback={<WidgetSkeleton config={config} />}>
      <OpenOceanWidget config={config} integrator="nextjs-example" />
    </ClientOnly>
  )
}

components/ClientOnly.tsx

'use client'

import { useEffect, useState } from 'react'

export function ClientOnly({ children, fallback = null }) {
  const [hasMounted, setHasMounted] = useState(false)

  useEffect(() => {
    setHasMounted(true)
  }, [])

  if (!hasMounted) {
    return fallback
  }

  return children
}

Key Points

• Use 'use client' directive for client components

• Implement ClientOnly wrapper to prevent SSR issues

• Use WidgetSkeleton as fallback during SSR

• Configure transpilePackages in next.config.js

---

Next.js (Pages Router)

Installation

Same as Next.js App Router.

Usage

pages/index.tsx

import { Widget } from '@/components/Widget'

export default function Home() {
  return (
    <main>
      <Widget />
    </main>
  )
}

components/Widget.tsx

Same implementation as App Router, but without 'use client' directive (not needed in Pages Router).

Key Points

• Similar to App Router but uses pages/ directory

• No need for 'use client' directive

• Still requires ClientOnly wrapper for SSR safety

---

Vue 3

Installation

npm install @openocean.finance/widget veaury
npm install --save-dev @vitejs/plugin-react @vitejs/plugin-vue

Configuration

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import react from '@vitejs/plugin-react'
import { nodePolyfills } from 'vite-plugin-node-polyfills'

export default defineConfig({
  plugins: [
    vue(),
    react(),
    nodePolyfills(),
  ],
})

Usage

src/components/Widget.vue

<template>
  <Widget :config="config" />
</template>

<script lang="ts">
import { OpenOceanWidget } from '@openocean.finance/widget'
import { applyPureReactInVue } from 'veaury'

export default {
  components: {
    Widget: applyPureReactInVue(OpenOceanWidget),
  },
  setup() {
    return {
      config: {
        theme: {
          container: {
            border: '1px solid rgb(234, 234, 234)',
            borderRadius: '16px',
          },
        },
        integrator: 'vue-example',
      },
    }
  },
}
</script>

Key Points

• Uses veaury to bridge React and Vue components

• Requires both Vue and React plugins in Vite

• Use applyPureReactInVue or applyReactInVue HOC

---

Nuxt 3

Installation

npm install @openocean.finance/widget veaury

Configuration

nuxt.config.ts

export default defineNuxtConfig({
  compatibilityDate: '2024-04-03',
  ssr: false, // Widget requires client-side rendering
})

Usage

components/WidgetContainer.vue

<template>
  <Widget :config="config" />
</template>

<script lang="ts">
import { OpenOceanWidget } from '@openocean.finance/widget'
import { applyPureReactInVue } from 'veaury'

export default {
  components: {
    Widget: applyPureReactInVue(OpenOceanWidget),
  },
  setup() {
    return {
      config: {
        theme: {
          container: {
            border: '1px solid rgb(234, 234, 234)',
            borderRadius: '16px',
          },
        },
        integrator: 'nuxt-example',
      },
    }
  },
}
</script>

app.vue

<template>
  <ClientOnly>
    <WidgetContainer />
  </ClientOnly>
</template>

Key Points

• Use ClientOnly component for SSR safety

• Disable SSR or use client-only rendering

• Same Vue-React bridge approach as Vue 3

---

Svelte

Installation

npm install @openocean.finance/widget
npm install --save-dev @vitejs/plugin-react @vitejs/plugin-svelte

Configuration

vite.config.ts

import { defineConfig } from 'vite'
import { svelte } from '@sveltejs/vite-plugin-svelte'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [svelte(), react()],
})

Usage

src/lib/OpenOceanWidget.svelte

<script>
import { OpenOceanWidget } from '@openocean.finance/widget'
import ReactAdapter from './ReactAdapter.svelte'
</script>

<ReactAdapter
  element={OpenOceanWidget}
  config={{
    theme: {
      container: {
        boxShadow: '0px 8px 32px rgba(0, 0, 0, 0.08)',
        borderRadius: '16px',
      },
    },
  }}
  integrator="svelte-example"
/>

src/lib/ReactAdapter.svelte

You'll need a React adapter component. Check the example for the full implementation.

Key Points

• Requires a React adapter to use React components in Svelte

• Both Svelte and React plugins needed

• Custom adapter implementation required

---

Remix

Installation

npm install @openocean.finance/widget @tanstack/react-query

Configuration

remix.config.js

/** @type {import('@remix-run/dev').AppConfig} */
module.exports = {
  serverModuleFormat: 'esm',
  future: {
    v2_errorBoundary: true,
    v2_meta: true,
    v2_normalizeFormMethod: true,
    v2_routeConvention: true,
  },
}

Usage

app/routes/_index.tsx

import { ClientOnly } from 'remix-utils/client-only'
import { Fallback } from '../components/Fallback'
import { OpenOceanWidget } from '../components/OpenOceanWidget'

export default function Index() {
  return (
    <ClientOnly fallback={<Fallback />}>
      {() => <OpenOceanWidget />}
    </ClientOnly>
  )
}

app/components/OpenOceanWidget.tsx

import { OpenOceanWidget } from '@openocean.finance/widget'
import { QueryClientProvider } from '@tanstack/react-query'
import { queryClient } from '../lib/queryClient'

export function OpenOceanWidget() {
  return (
    <QueryClientProvider client={queryClient}>
      <OpenOceanWidget
        integrator="remix-example"
        config={{
          theme: {
            container: {
              border: '1px solid rgb(234, 234, 234)',
              borderRadius: '16px',
            },
          },
        }}
      />
    </QueryClientProvider>
  )
}

Key Points

• Requires React Query provider

• Server-side rendering support

• Configure Remix for ES modules

---

RainbowKit

Installation

npm install @openocean.finance/widget @rainbow-me/rainbowkit wagmi viem
npm install @tanstack/react-query

Configuration

src/config/wagmi.ts

import { getDefaultConfig } from '@rainbow-me/rainbowkit'
import { mainnet, polygon, optimism, arbitrum, base } from 'wagmi/chains'

export const config = getDefaultConfig({
  appName: 'OpenOcean Widget Example',
  projectId: 'YOUR_PROJECT_ID',
  chains: [mainnet, polygon, optimism, arbitrum, base],
  ssr: true,
})

Usage

src/App.tsx

import { OpenOceanWidget } from '@openocean.finance/widget'
import { ConnectButton, useConnectModal } from '@rainbow-me/rainbowkit'
import { WagmiProvider } from 'wagmi'
import { QueryClientProvider } from '@tanstack/react-query'
import { config } from './config/wagmi'
import { queryClient } from './config/queryClient'

export default function App() {
  const { openConnectModal } = useConnectModal()
  
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <RainbowKitProvider>
          <ConnectButton chainStatus="none" />
          <OpenOceanWidget
            config={{
              walletConfig: {
                onConnect() {
                  openConnectModal?.()
                },
              },
              theme: {
                container: {
                  boxShadow: '0px 8px 32px rgba(0, 0, 0, 0.08)',
                  borderRadius: '16px',
                },
              },
            }}
            integrator="rainbowkit-example"
          />
        </RainbowKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}

Key Points

• Integrates with RainbowKit wallet connection

• Uses walletConfig.onConnect to trigger RainbowKit modal

• Requires Wagmi and React Query setup

---

ConnectKit

Installation

npm install @openocean.finance/widget @openocean.finance/wallet-management
npm install connectkit wagmi viem @tanstack/react-query

Configuration

src/config/queryClient.ts

import { QueryClient } from '@tanstack/react-query'

export const queryClient = new QueryClient()

src/providers/WalletProvider.tsx

Set up ConnectKit wallet provider. See example for full implementation.

Usage

src/App.tsx

import { OpenOceanWidget } from '@openocean.finance/widget'
import { QueryClientProvider } from '@tanstack/react-query'
import { WalletProvider } from './providers/WalletProvider'
import { queryClient } from './config/queryClient'

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <WalletProvider>
        <OpenOceanWidget
          integrator="widget-connectkit-example"
          config={{
            theme: {
              container: {
                border: '1px solid rgb(234, 234, 234)',
                borderRadius: '16px',
              },
            },
          }}
        />
      </WalletProvider>
    </QueryClientProvider>
  )
}

Key Points

• Uses OpenOcean's wallet-management package

• Integrates with ConnectKit

• Requires QueryClient setup

---

Privy

Installation

npm install @openocean.finance/widget @privy-io/react-auth
npm install @tanstack/react-query

Configuration

src/config/queryClient.ts

import { QueryClient } from '@tanstack/react-query'

export const queryClient = new QueryClient()

Usage

src/App.tsx

import { OpenOceanWidget } from '@openocean.finance/widget'
import { PrivyProvider } from '@privy-io/react-auth'
import { QueryClientProvider } from '@tanstack/react-query'
import { queryClient } from './config/queryClient'

function App() {
  return (
    <PrivyProvider
      appId="YOUR_PRIVY_APP_ID"
      config={{
        loginMethods: ['wallet', 'email', 'sms'],
      }}
    >
      <QueryClientProvider client={queryClient}>
        <OpenOceanWidget
          integrator="privy-example"
          config={{
            theme: {
              container: {
                border: '1px solid rgb(234, 234, 234)',
                borderRadius: '16px',
              },
            },
          }}
        />
      </QueryClientProvider>
    </PrivyProvider>
  )
}

Key Points

• Integrates with Privy authentication

• Supports multiple login methods

• Requires Privy app ID

---

Privy + Ethers

Installation

npm install @openocean.finance/widget @privy-io/react-auth ethers
npm install @tanstack/react-query

Usage

Similar to Privy example but with Ethers.js integration for wallet operations.

Key Points

• Extends Privy with Ethers.js

• Provides more wallet control

• See example for wallet provider implementation

---

Reown (WalletConnect)

Installation

npm install @openocean.finance/widget @reown/appkit @reown/appkit-adapter-wagmi
npm install wagmi viem @tanstack/react-query

Configuration

src/config/wagmi.ts

import { createConfig, http } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'
import { createAppKit } from '@reown/appkit/react'
import { WagmiAdapter } from '@reown/appkit-adapter-wagmi'

const metadata = {
  name: 'OpenOcean Widget',
  description: 'OpenOcean Widget Example',
  url: 'https://openocean.finance',
  icons: ['https://openocean.finance/favicon.ico'],
}

const wagmiAdapter = new WagmiAdapter({
  ssr: true,
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

createAppKit({
  adapters: [wagmiAdapter],
  chains: [mainnet, sepolia],
  projectId: 'YOUR_PROJECT_ID',
  metadata,
})

Usage

src/App.tsx

import { OpenOceanWidget } from '@openocean.finance/widget'
import { WagmiProvider } from 'wagmi'
import { QueryClientProvider } from '@tanstack/react-query'
import { config } from './config/wagmi'
import { queryClient } from './config/queryClient'

export default function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <OpenOceanWidget
          integrator="reown-example"
          config={{
            theme: {
              container: {
                border: '1px solid rgb(234, 234, 234)',
                borderRadius: '16px',
              },
            },
          }}
        />
      </QueryClientProvider>
    </WagmiProvider>
  )
}

Key Points

• Uses Reown (WalletConnect v4)

• Requires project ID from WalletConnect Cloud

• Full Wagmi integration

---

Dynamic

Installation

npm install @openocean.finance/widget @dynamic-labs/sdk-react-core
npm install @tanstack/react-query

Configuration

src/config/dynamic.ts

import { DynamicContextProvider } from '@dynamic-labs/sdk-react-core'

export const dynamicConfig = {
  environmentId: 'YOUR_ENVIRONMENT_ID',
}

Usage

src/App.tsx

import { OpenOceanWidget } from '@openocean.finance/widget'
import { DynamicContextProvider } from '@dynamic-labs/sdk-react-core'
import { QueryClientProvider } from '@tanstack/react-query'
import { queryClient } from './config/queryClient'
import { dynamicConfig } from './config/dynamic'

function App() {
  return (
    <DynamicContextProvider settings={dynamicConfig}>
      <QueryClientProvider client={queryClient}>
        <OpenOceanWidget
          integrator="dynamic-example"
          config={{
            theme: {
              container: {
                border: '1px solid rgb(234, 234, 234)',
                borderRadius: '16px',
              },
            },
          }}
        />
      </QueryClientProvider>
    </DynamicContextProvider>
  )
}

Key Points

• Integrates with Dynamic Labs wallet SDK

• Requires environment ID

• Supports multiple wallet types

---

Zustand Widget Config

Installation

npm install @openocean.finance/widget zustand
npm install @mui/material

Usage

This example demonstrates using Zustand for widget configuration state management with form controls.

src/store/createWidgetConfigStore.ts

import { create } from 'zustand'
import type { WidgetConfig } from '@openocean.finance/widget'

interface WidgetConfigState {
  config: Partial<WidgetConfig>
  setConfig: (config: Partial<WidgetConfig>) => void
  setFormValues: (formValues: Partial<WidgetConfig>) => void
}

export const useWidgetConfigStore = create<WidgetConfigState>((set, get) => ({
  config: {
    buildUrl: true,
    theme: {
      container: {
        border: '1px solid rgb(234, 234, 234)',
        borderRadius: '16px',
      },
    },
  },
  setConfig: (config) => set({ config }),
  setFormValues: (formValues) => {
    const currentConfig = get().config ?? {}
    // Remove updatable form values
    const { fromAmount, fromChain, fromToken, toAddress, toChain, toToken, ...rest } = currentConfig
    set({
      config: {
        ...rest,
        ...formValues,
      },
    })
  },
}))

src/App.tsx

import { Box } from '@mui/material'
import { FormControls } from './components/FormControls'
import { WidgetView } from './components/WidgetView'

function App() {
  return (
    <Box sx={{ display: 'flex', gap: 2 }}>
      <FormControls />
      <WidgetView />
    </Box>
  )
}

src/components/WidgetView.tsx

import { OpenOceanWidget } from '@openocean.finance/widget'
import { useWidgetConfigStore } from '../store/createWidgetConfigStore'

export function WidgetView() {
  const config = useWidgetConfigStore((state) => state.config)

  return (
    <OpenOceanWidget
      integrator="zustand-example"
      config={config}
    />
  )
}

Key Points

• Uses Zustand for state management

• Separates form controls from widget view

• Allows dynamic widget configuration updates

• Good for complex state management scenarios

• Supports form value updates without affecting other config

---

Deposit Flow

Installation

npm install @openocean.finance/widget

Usage

This example demonstrates a deposit flow integration with custom contract calls and deposit card.

src/App.tsx

import type { ContractCall, WidgetConfig } from '@openocean.finance/widget'
import {
  ChainType,
  CoinKey,
  DisabledUI,
  HiddenUI,
  OpenOceanWidget,
} from '@openocean.finance/widget'
import { useMemo } from 'react'
import { DepositCard } from './components/DepositCard'
import { contractTool } from './config'

const depositAddress = '0x4bF3E32de155359D1D75e8B474b66848221142fc'
const contractCalls: ContractCall[] = []

export function App() {
  const widgetConfig: WidgetConfig = useMemo(() => {
    return {
      toAddress: {
        ...contractTool,
        address: depositAddress,
        chainType: ChainType.EVM,
      },
      subvariant: 'custom',
      subvariantOptions: { custom: 'deposit' },
      integrator: 'ProtocolName',
      disabledUI: [DisabledUI.ToAddress],
      hiddenUI: [HiddenUI.Appearance, HiddenUI.Language],
      useRecommendedRoute: true,
      theme: {
        container: {
          border: '1px solid rgb(234, 234, 234)',
          borderRadius: '16px',
        },
      },
    }
  }, [])

  return (
    <OpenOceanWidget
      contractComponent={
        <DepositCard
          token={{
            chainId: 10,
            address: '0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85',
            symbol: 'USDC',
            name: 'USD Coin',
            decimals: 6,
            priceUSD: '1',
            coinKey: CoinKey.USDC,
            logoURI: '...',
          }}
          contractCalls={contractCalls}
        />
      }
      contractTool={contractTool}
      config={widgetConfig}
      integrator={widgetConfig.integrator}
    />
  )
}

Key Points

• Custom deposit flow with contract calls

• Uses subvariant: 'custom' with custom: 'deposit'

• Custom contractComponent for deposit UI

• Disables and hides specific UI elements

• Requires contractTool configuration

---

Common Configuration Options

All examples support these common configuration options:

{
  integrator: string, // Required: Your integrator identifier
  variant?: 'wide' | 'compact' | 'drawer',
  subvariant?: 'split' | 'bridge' | 'swap',
  appearance?: 'light' | 'dark' | 'auto',
  theme?: {
    container?: {
      border?: string,
      borderRadius?: string,
      boxShadow?: string,
    },
    // ... more theme options
  },
  chains?: {
    allow?: number[],
    deny?: number[],
  },
  buildUrl?: boolean,
  // ... more config options
}

Troubleshooting

SSR Issues

• Use ClientOnly wrapper in Next.js/Nuxt

• Disable SSR if not needed

• Use WidgetSkeleton as fallback

Wallet Connection Issues

• Ensure wallet providers are properly configured

• Check network/chain configurations

• Verify API keys and project IDs

Build Issues

• Install required polyfills (buffer, process)

• Configure Vite/Rollup for React components

• Check transpilePackages in Next.js config

Support

For more information, visit:

• OpenOcean Documentation

• GitHub Repository