@reserve-protocol/react-zapper

A React component library for integrating DTF (Decentralized Token Folio) zap functionality into your Web3 applications. This package provides a complete zapping solution with support for both modal and inline modes, built on top of Wagmi v2.

📖 Live Demo

Features

• 🔄 Zap Minting: Convert any supported token directly into DTF tokens
• 🔄 Zap Redeeming: Convert DTF tokens back to any supported token
• 🎨 Flexible UI: Three display modes - modal popup, inline embedded, and simple launcher
• 🎯 Modern Stack: Built with Wagmi v2, Viem, RainbowKit v2, and TanStack Query v5
• ⚡ Optimized: Real-time price updates and slippage protection
• 🛡️ Type Safe: Full TypeScript support
• 🎨 Styled: Uses Tailwind CSS with CSS injection

Installation

npm install @reserve-protocol/react-zapper

Peer Dependencies

Make sure you have these peer dependencies installed:

npm install react@^18.0.0 @tanstack/react-query@^5.87.4 wagmi@^2.15.14

Note: viem will be installed automatically as a dependency of wagmi.

Quick Start

1. Import Components and Styles

Import the components you need and the CSS file for styling:

import { Zapper, useZapperModal, Toaster } from '@reserve-protocol/react-zapper'
import '@reserve-protocol/react-zapper/styles.css'

Note for Tailwind users: If your project already has Tailwind CSS configured, you can skip the CSS import and add the package to your Tailwind content configuration:

// tailwind.config.js
module.exports = {
  content: [
    // ... your other content paths
    './node_modules/@reserve-protocol/react-zapper/dist/**/*.js',
  ],
  // ... rest of your config
}

2. Basic Modal Usage

import { Zapper, useZapperModal, Toaster } from '@reserve-protocol/react-zapper'
import '@reserve-protocol/react-zapper/styles.css'
import { wagmiConfig } from './wagmi-config'

function MyApp() {
  const { open } = useZapperModal()

  return (
    <>
      <Zapper
        wagmiConfig={wagmiConfig}
        chain={1} // Ethereum mainnet
        dtfAddress="0x123..." // Your DTF contract address
        mode="modal"
      />

      <button onClick={open}>Open Zapper</button>

      <Toaster position="bottom-right" />
    </>
  )
}

3. Inline Usage

import { Zapper } from '@reserve-protocol/react-zapper'
import '@reserve-protocol/react-zapper/styles.css'
import { useConfig } from 'wagmi'

function ZapperPage() {
  const wagmiConfig = useConfig()

  return (
    <div className="max-w-md mx-auto">
      <h1>Zap into My DTF</h1>
      <Zapper
        wagmiConfig={wagmiConfig}
        chain={1}
        dtfAddress="0x123..."
        mode="inline"
      />
    </div>
  )
}

4. Simple Mode Usage

The simple mode provides a streamlined launcher interface that pre-loads quotes before opening the full modal:

import { Zapper } from '@reserve-protocol/react-zapper'
import '@reserve-protocol/react-zapper/styles.css'
import { wagmiConfig } from './wagmi-config'

function SimpleZapper() {
  return (
    <Zapper
      wagmiConfig={wagmiConfig}
      chain={1}
      dtfAddress="0x123..."
      mode="simple"
    />
  )
}

Simple mode features:

• Launcher Pattern: Shows a minimal input interface with "Get started" button
• Pre-loading: Fetches quotes in the background as the user types
• Modal Transition: Clicking "Get started" opens the full modal with:
  • Input amount preserved
  • Quote already loaded
  • All transaction details and controls available
• Clean Entry Point: Perfect for embedding in landing pages or simplified UIs
• User-Friendly: Reduces cognitive load with a two-step process

Props

ZapperProps

| Property | Type | Required | Description | | ---------------- | ------------------------------- | -------- | ---------------------------------------------- | | wagmiConfig | WagmiConfig | ✅ | Wagmi v2 configuration for the app | | chain | number | ✅ | Chain ID where the DTF is deployed | | dtfAddress | Address | ✅ | DTF contract address | | mode | 'modal' \| 'inline' \| 'simple' | ❌ | Display mode: 'modal' (popup), 'inline' (embedded), 'simple' (launcher) | | apiUrl | string | ❌ | Custom API endpoint (defaults to Reserve API) | | connectWallet | () => void | ❌ | Function to trigger wallet connection | | debug | boolean | ❌ | Enable debug mode to show additional info | | defaultSource | QuoteSource | ❌ | Default quote source ('best', 'zap', or 'odos')| | className | string | ❌ | Additional CSS classes |

useZapperModal Hook

The useZapperModal hook provides control over the modal state:

const { isOpen, open, close } = useZapperModal()

Advanced Usage

With Custom Error Handling

import { Zapper, Toaster } from '@reserve-protocol/react-zapper'
import { toast } from 'sonner'
import { wagmiConfig } from './wagmi-config'

function AdvancedZapper() {
  return (
    <>
      <Zapper
        wagmiConfig={wagmiConfig}
        chain={1}
        dtfAddress="0x123..."
        mode="modal"
      />
      <Toaster />
    </>
  )
}

With Custom API Endpoint

<Zapper
  chain={1}
  dtfAddress="0x123..."
  apiUrl="https://custom-api.example.com"
  mode="inline"
/>

With Custom Wallet Connection

import { useConnectModal } from '@rainbow-me/rainbowkit'

function ZapperWithCustomWallet() {
  const { openConnectModal } = useConnectModal()

  return (
    <Zapper
      wagmiConfig={wagmiConfig}
      chain={1}
      dtfAddress="0x123..."
      mode="modal"
      connectWallet={openConnectModal}
    />
  )
}

Setting Custom API URL Globally

import { setCustomApiUrl } from '@reserve-protocol/react-zapper'

// Set once at app initialization
setCustomApiUrl('https://custom-api.example.com')

Supported Chains

The zapper currently supports:

• Ethereum Mainnet (Chain ID: 1)
• Base (Chain ID: 8453)
• BNB Smart Chain (Chain ID: 56)

Each chain has its own set of supported tokens for zapping. The component automatically detects the current chain and shows appropriate tokens.

Styling

The package uses Tailwind CSS for styling. You need to import the styles:

import '@reserve-protocol/react-zapper/styles.css'

• Projects WITHOUT Tailwind: The imported CSS file includes all necessary styles
• Projects WITH Tailwind: You can optionally skip the CSS import and configure Tailwind to process the package files (see Quick Start section)
• Custom Styling: The package uses CSS variables for theming, making it easy to override colors and styles

The component respects your application's font family by default.

Custom Fonts

To use custom fonts, ensure they are loaded in your application and the package will inherit them automatically.

API Integration

The package integrates with the Reserve Protocol's zapper API for:

• Real-time swap quotes
• Price impact calculations
• Transaction routing optimization
• Health status monitoring

TypeScript Support

Full TypeScript support is included with exported types:

import type {
  ZapperProps,
  UseZapperModalReturn,
  Token,
  TokenBalance,
} from '@reserve-protocol/react-zapper'

Development

Prerequisites

• Node.js 16+
• npm or yarn

Setup

# Install dependencies
npm install

# Start development server with demo
npm run dev

# Build the package
npm run build

Demo Application

The package includes a demo application that showcases both modal and inline modes:

npm run dev

Visit http://localhost:5173 to see the demo.

License

MIT License - see LICENSE file for details.