Zealous Swap Widget

ZealousSwapWidget is a sleek, customizable React component for seamless cryptocurrency swapping. Built on top of Wagmi, RainbowKit, and Material-UI, it offers multi-wallet support and a smooth user experience—designed to plug directly into any dApp with minimal setup.

Power your platform with the flexibility, speed, and style of Zealous Swap.

Features

• 🔗 Multi-wallet Support - MetaMask, OKX, OneKey, Rabby, WalletConnect, SafePal, TokenPocket, Kastle, Trust Wallet, Gate, Bitget
• 🌐 Network Security - Only supports Kasplex Mainnet with automatic filtering
• 🎨 Fully Customizable - Colors, fonts, spacing, and dark/light modes
• 🌍 Internationalization - Multi-language support with i18next
• 📱 Responsive Design - Adapts to different screen sizes
• ⚡ Modern Stack - React, Wagmi v2, RainbowKit, Material-UI
• 🔧 Flexible Integration - Use standalone or with existing Wagmi/QueryClient providers
• 💱 Token Preselection - Pre-configure source and target tokens

Installation

# NPM
npm install zealous-swap-widget @rainbow-me/rainbowkit @mui/[email protected] @mui/[email protected] @mui/[email protected] @emotion/[email protected] @emotion/[email protected]

# Yarn
yarn add zealous-swap-widget @rainbow-me/rainbowkit @mui/[email protected] @mui/[email protected] @mui/[email protected] @emotion/[email protected] @emotion/[email protected]

Required CSS Import:

import "@rainbow-me/rainbowkit/styles.css";

Quick Start

Standalone Usage (Simple)

Perfect for quick integration:

import { ZealousSwapWidget } from "zealous-swap-widget";

function App() {
  return (
    <ZealousSwapWidget
      projectId="your-walletconnect-project-id"
      primaryColor="#6040FF"
      darkMode={false}
    />
  );
}

Integration with Existing Providers (Recommended)

For dApps with existing Wagmi/QueryClient setup - shares wallet connections and improves performance:

import { ZealousSwapWidget } from "zealous-swap-widget";
import { useConfig } from "wagmi";
import { useQueryClient } from "@tanstack/react-query";

function App() {
  const wagmiConfig = useConfig();
  const queryClient = useQueryClient();

  return (
    <ZealousSwapWidget
      wagmiConfig={wagmiConfig}
      queryClient={queryClient}
      primaryColor="#6040FF"
      darkMode={false}
    />
  );
}

Token Preselection

You can preselect tokens for the swap interface:

Default Behavior

If no tokenFrom is specified, the widget automatically uses the default network token (KAS for Kasplex):

// Uses KAS as default tokenFrom
<ZealousSwapWidget />

Custom Token Selection

Specify both source and target tokens:

// Swap from KAS to a specific token
<ZealousSwapWidget
  tokenFrom="KAS"
  tokenTo="0x2c2Ae87Ba178F48637acAe54B87c3924F544a83e"
/>

// Use custom token addresses
<ZealousSwapWidget
  tokenFrom="0x2c2Ae87Ba178F48637acAe54B87c3924F544a83e"
  tokenTo="0x1D3b1f5bF52540a4ABCE6c22c66d9A5BE04A557B"
/>

Token Examples for Kasplex

// Example 1: KAS to WKAS
<ZealousSwapWidget
  tokenFrom="KAS"
  tokenTo="0x2c2Ae87Ba178F48637acAe54B87c3924F544a83e"
/>

// Example 2: Let tokenFrom default to KAS, swap to Nacho
<ZealousSwapWidget
  tokenTo="0x1D3b1f5bF52540a4ABCE6c22c66d9A5BE04A557B"
/>

// Example 3: WKAS to Zeal
<ZealousSwapWidget
  tokenFrom="0x2c2Ae87Ba178F48637acAe54B87c3924F544a83e"
  tokenTo="0x293709CE67f20aDD9582186BBDB380F6e73E5045"
/>

// Example 4: Nacho to KAS
<ZealousSwapWidget
  tokenFrom="0x1D3b1f5bF52540a4ABCE6c22c66d9A5BE04A557B"
  tokenTo="KAS"
/>

Popular Mainnet Tokens

| Token | Address | Symbol | | ----------- | -------------------------------------------- | ------ | | Wrapped KAS | 0x2c2Ae87Ba178F48637acAe54B87c3924F544a83e | WKAS | | Nacho | 0x1D3b1f5bF52540a4ABCE6c22c66d9A5BE04A557B | Nacho | | Zeal | 0x293709CE67f20aDD9582186BBDB380F6e73E5045 | Zeal |

Network Support

⚠️ Security Feature: Only Kasplex Mainnet is supported:

• Kasplex (ID: 202555)

Unsupported networks are automatically filtered out with console warnings.

import { ZealousSwapWidget, Kasplex } from "zealous-swap-widget";

// Use Kasplex
<ZealousSwapWidget networks={[Kasplex]} />;

// Mixed networks (unsupported ones filtered automatically)
const mixedNetworks = [Kasplex, { id: 1, name: "Ethereum" }]; // Ethereum filtered out
<ZealousSwapWidget networks={mixedNetworks} />;

Configuration

| Prop | Type | Default | Description | | ------------------------- | ------------- | ----------------------------------------------------- | -------------------------------------------- | | wagmiConfig | Config | undefined | External Wagmi config (optional) | | queryClient | QueryClient | undefined | External QueryClient instance (optional) | | projectId | string | "403fedeb1554f5af94f6cccc681849f2" | WalletConnect project ID | | networks | Array | [Kasplex] | Supported networks only | | languageCode | string | "en" | Language code (en, es, fr, zh, de, ja, etc.) | | primaryColor | string | "#6040FF" | Primary theme color | | secondaryColor | string | "#1B263B" | Secondary theme color | | darkMode | boolean | false | Enable dark mode | | backgroundColor | string | "#ffffff" | Background color | | fontFamily | string | "'Poppins', 'Roboto', 'Helvetica Neue', sans-serif" | Font family | | paddingTop | number | 0 | Top padding in pixels | | paddingBottom | number | 0 | Bottom padding in pixels | | paddingLeft | number | 0 | Left padding in pixels | | paddingRight | number | 0 | Right padding in pixels | | maxWidth | number | 480 | Maximum width in pixels | | isShownNetwork | boolean | true | Show/hide network selector icon | | tokenFrom | string | Network default token (KAS for Kasplex) | Source token symbol or address | | tokenTo | string | undefined | Target token symbol or address | | tokenFromInputBg | string | undefined | Background color for source token input | | tokenToInputBg | string | undefined | Background color for target token input | | iconsColor | string | undefined | Color for icons throughout the widget | | titleColor | string | undefined | Color for titles and headings | | buttonsBackground | string | undefined | Background color for buttons | | ballanceBackground | string | undefined | Background color for balance displays | | buttonEnabledTextColor | string | undefined | Text color for enabled buttons | | buttonDisabledTextColor | string | undefined | Text color for disabled buttons | | warningMessageTextColor | string | undefined | Text color for warning messages |

Theming Examples

// Dark Mode with custom styling - KAS to WKAS
<ZealousSwapWidget
  darkMode={true}
  primaryColor="#BB86FC"
  backgroundColor="#121212"
  tokenFrom="KAS"
  tokenTo="0x2c2Ae87Ba178F48637acAe54B87c3924F544a83e"
  tokenFromInputBg="rgba(31, 41, 55, 1)"
  tokenToInputBg="rgba(31, 41, 55, 0.5)"
  iconsColor="#FFF"
  titleColor="#FFF"
  buttonsBackground="#14B8A6"
  ballanceBackground="#9CA3AF"
  buttonEnabledTextColor="#FFFFFF"
  buttonDisabledTextColor="#9CA3AF"
  warningMessageTextColor="#F59E0B"
/>

// Custom Brand with Button Text Colors - WKAS to Nacho
<ZealousSwapWidget
  primaryColor="#FF6B35"
  secondaryColor="#004E89"
  fontFamily="'Inter', sans-serif"
  tokenFrom="0x2c2Ae87Ba178F48637acAe54B87c3924F544a83e"
  tokenTo="0x1D3b1f5bF52540a4ABCE6c22c66d9A5BE04A557B"
  buttonsBackground="#FF6B35"
  titleColor="#004E89"
  buttonEnabledTextColor="#FFFFFF"
  buttonDisabledTextColor="#6B7280"
  warningMessageTextColor="#DC2626"
/>

// Compact Layout with Custom Colors - Nacho to Zeal
<ZealousSwapWidget
  maxWidth={320}
  paddingTop={10}
  paddingLeft={15}
  tokenFrom="0x1D3b1f5bF52540a4ABCE6c22c66d9A5BE04A557B"
  tokenTo="0x293709CE67f20aDD9582186BBDB380F6e73E5045"
  tokenFromInputBg="#F3F4F6"
  tokenToInputBg="#F9FAFB"
  iconsColor="#6B7280"
  ballanceBackground="#E5E7EB"
  buttonEnabledTextColor="#1F2937"
  buttonDisabledTextColor="#9CA3AF"
  warningMessageTextColor="#EF4444"
/>

// Glassmorphism Style with Enhanced Text Colors - Zeal to KAS
<ZealousSwapWidget
  darkMode={true}
  backgroundColor="rgba(0, 0, 0, 0.8)"
  tokenFrom="0x293709CE67f20aDD9582186BBDB380F6e73E5045"
  tokenTo="KAS"
  tokenFromInputBg="rgba(255, 255, 255, 0.1)"
  tokenToInputBg="rgba(255, 255, 255, 0.05)"
  iconsColor="#FFFFFF"
  titleColor="#FFFFFF"
  buttonsBackground="rgba(96, 64, 255, 0.8)"
  ballanceBackground="rgba(255, 255, 255, 0.15)"
  buttonEnabledTextColor="#FFFFFF"
  buttonDisabledTextColor="rgba(255, 255, 255, 0.5)"
  warningMessageTextColor="#FBBF24"
/>

Complete Integration Example

import React from "react";
import ReactDOM from "react-dom/client";
import { WagmiProvider, createConfig, http } from "wagmi";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { RainbowKitProvider } from "@rainbow-me/rainbowkit";
import { ZealousSwapWidget, Kasplex } from "zealous-swap-widget";
import { useConfig } from "wagmi";
import { useQueryClient } from "@tanstack/react-query";
import "@rainbow-me/rainbowkit/styles.css";

const config = createConfig({
  chains: [Kasplex],
  transports: { [Kasplex.id]: http() },
});

const queryClient = new QueryClient();

function App() {
  const wagmiConfig = useConfig();
  const queryClient = useQueryClient();

  return (
    <div>
      <h1>My dApp</h1>
      <ZealousSwapWidget
        wagmiConfig={wagmiConfig}
        queryClient={queryClient}
        primaryColor="#6040FF"
        maxWidth={480}
        tokenFrom="KAS"
        tokenTo="0x2c2Ae87Ba178F48637acAe54B87c3924F544a83e"
        tokenFromInputBg="rgba(31, 41, 55, 1)"
        tokenToInputBg="rgba(31, 41, 55, 0.5)"
        iconsColor="#FFF"
        titleColor="#FFF"
        buttonsBackground="#14B8A6"
        ballanceBackground="#9CA3AF"
        buttonEnabledTextColor="#FFFFFF"
        buttonDisabledTextColor="#6B7280"
        warningMessageTextColor="#F59E0B"
      />
    </div>
  );
}

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(
  <WagmiProvider config={config}>
    <QueryClientProvider client={queryClient}>
      <RainbowKitProvider>
        <App />
      </RainbowKitProvider>
    </QueryClientProvider>
  </WagmiProvider>
);

UI Customization Features

The widget now supports granular UI customization for creating unique branded experiences:

Input Field Styling

• tokenFromInputBg - Customize source token input background
• tokenToInputBg - Customize target token input background

Visual Elements

• iconsColor - Control icon colors throughout the interface
• titleColor - Customize heading and title colors
• buttonsBackground - Set custom button background colors
• ballanceBackground - Style balance display backgrounds

Button Text Styling

• buttonEnabledTextColor - Text color for enabled/active buttons
• buttonDisabledTextColor - Text color for disabled buttons
• warningMessageTextColor - Text color for warning and error messages

Popular Color Combinations

Professional Dark Theme:

tokenFromInputBg = "rgba(31, 41, 55, 1)";
tokenToInputBg = "rgba(31, 41, 55, 0.5)";
iconsColor = "#FFF";
titleColor = "#FFF";
buttonsBackground = "#14B8A6";
ballanceBackground = "#9CA3AF";
buttonEnabledTextColor = "#FFFFFF";
buttonDisabledTextColor = "#6B7280";
warningMessageTextColor = "#F59E0B";

Clean Light Theme:

tokenFromInputBg = "#F8FAFC";
tokenToInputBg = "#F1F5F9";
iconsColor = "#475569";
titleColor = "#1E293B";
buttonsBackground = "#3B82F6";
ballanceBackground = "#E2E8F0";
buttonEnabledTextColor = "#FFFFFF";
buttonDisabledTextColor = "#94A3B8";
warningMessageTextColor = "#DC2626";

High Contrast Theme:

buttonEnabledTextColor = "#000000";
buttonDisabledTextColor = "#A0A0A0";
warningMessageTextColor = "#FF0000";
buttonsBackground = "#FFFF00";

Internationalization

Supports 15+ languages:

| Code | Language | Code | Language | Code | Language | | ---- | -------- | ---- | ---------- | ---- | ---------- | | en | English | fr | French | es | Spanish | | zh | Chinese | de | German | ja | Japanese | | ru | Russian | ar | Arabic | ko | Korean | | it | Italian | pt | Portuguese | tr | Turkish | | el | Greek | pl | Polish | id | Indonesian |

<ZealousSwapWidget
  languageCode="es"
  tokenFrom="KAS"
  tokenTo="0x2c2Ae87Ba178F48637acAe54B87c3924F544a83e"
/> // Spanish

WalletConnect Setup

1. Create a project at WalletConnect Cloud
2. Get your project ID
3. Pass it via the projectId prop

Benefits of Provider Integration

When using external wagmiConfig and queryClient:

• ✅ Shared wallet state across your app
• ✅ Better performance with shared data cache
• ✅ No provider conflicts
• ✅ Unified user experience

Troubleshooting

Network warnings in console? Only use supported networks: Kasplex (202555)

Duplicate provider errors? Use the external provider integration method

Token not found? Make sure the token symbol or address is valid for the selected network

Styling not applying? Ensure color values are valid CSS colors (hex, rgba, etc.)

Button text not visible? Check your buttonEnabledTextColor and buttonDisabledTextColor contrast against buttonsBackground

Support

Contact us via Telegram:

• https://t.me/ramy_lahoud
• https://t.me/louissaad