npm package: @louissaadgo/zealous-swap-widget
Description: Embeddable React swap widget for DEX platforms
Author: Ramy Lahoud
Latest version: 1.0.1

# 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

```bash
# NPM
npm install zealous-swap-widget @rainbow-me/rainbowkit @mui/material @mui/icons-material @emotion/react @emotion/styled react react-dom wagmi @tanstack/react-query @reduxjs/toolkit react-redux react-i18next i18next i18next-browser-languagedetector

# Yarn
yarn add zealous-swap-widget @rainbow-me/rainbowkit @mui/material @mui/icons-material @emotion/react @emotion/styled react react-dom wagmi @tanstack/react-query @reduxjs/toolkit react-redux react-i18next i18next i18next-browser-languagedetector
```

**Required CSS Import:**

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

## Quick Start

### Standalone Usage (Simple)

Perfect for quick integration:

```jsx
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:

```jsx
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):

```jsx
// Uses KAS as default tokenFrom
<ZealousSwapWidget />
```

### Custom Token Selection

Specify both source and target tokens:

```jsx
// 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

```jsx
// 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.

```jsx
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

```jsx
// 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

```jsx
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:**

```jsx
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:**

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

**High Contrast Theme:**

```jsx
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 |

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

## WalletConnect Setup

1. Create a project at [WalletConnect Cloud](https://cloud.walletconnect.com/)
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`