interop-widget

Interop Widget

A React widget for cross-chain asset bridging with customizable themes, default route configuration, and advanced UI components.

Installation

npm install interop-widget

Basic Usage

import { InteropWidget } from 'interop-widget';
import 'interop-widget/style.css';

// Use with default theme
<InteropWidget />

// Use with custom theme
<InteropWidget theme={customTheme} />

// Use with default route configuration
<InteropWidget defaultRouteConfig={routeConfig} />

// Use with both theme and route config
<InteropWidget 
  theme={customTheme} 
  defaultRouteConfig={routeConfig} 
/>

Features

• Cross-chain bridging - Seamless asset transfers between chains
• Customizable themes - Light, dark, and custom themes
• Default route configuration - Pre-select source/destination chains and tokens
• Advanced UI components - Tooltip, Modal, Toast, and more
• CSS isolation - No conflicts with host applications
• TypeScript support - Full type safety
• Responsive design - Works on all screen sizes

Tailwind CSS with Prefix

This widget uses Tailwind CSS v3 with the iw- prefix to prevent conflicts with host applications. All widget styles are prefixed with iw- to ensure complete isolation.

Benefits:

• No CSS conflicts - All classes are prefixed with iw-
• Works with any Tailwind version - v1, v2, v3, v4
• Works with any CSS framework - Bootstrap, Material-UI, etc.
• Self-contained styling - Widget styles don't interfere with host styles

Usage:

import { InteropWidget } from 'interop-widget';
import 'interop-widget/style.css';

<InteropWidget />

Class Examples:

Instead of standard Tailwind classes, the widget uses prefixed classes:

• mx-auto → iw-mx-auto
• flex → iw-flex
• p-4 → iw-p-4
• text-center → iw-text-center

Default Route Configuration

You can pre-configure the widget with default source and destination chains and tokens:

import { InteropWidget } from 'interop-widget';

const defaultRouteConfig = {
  fromChain: 'BNB Chain',
  fromToken: 'BTCB',
  toChain: 'Base',
  toToken: 'CBBTC'
};

<InteropWidget defaultRouteConfig={defaultRouteConfig} />

Supported Chains and Tokens

The widget currently supports BSC and Base chains with their respective Bitcoin tokens. See the Configuration Guide for the complete list.

Advanced Components

Tooltip Component

The widget includes a powerful tooltip component that renders outside parent containers to avoid overflow issues:

import { Tooltip } from 'interop-widget';

<Tooltip content="This is a tooltip" direction="top">
  <button>Hover me</button>
</Tooltip>

Features:

• Multiple directions (top, bottom, left, right)
• Portal rendering (no overflow issues)
• Customizable delay
• Theme integration
• Click outside to close

Modal Component

import { Modal } from 'interop-widget';

<Modal isOpen={isModalOpen} onClose={() => setIsModalOpen(false)}>
  <h2>Modal Content</h2>
  <p>This is a modal dialog.</p>
</Modal>

Toast System

The widget includes a global toast notification system that can be used throughout your application:

Using the useToast Hook (Recommended)

import { useToast } from 'interop-widget';

function MyComponent() {
  const { success, error, warning, info } = useToast();

  const handleSuccess = () => {
    success('Transaction Complete!', 'Your swap was successful');
  };

  const handleError = () => {
    error('Transaction Failed', 'Insufficient balance');
  };

  const handleWarning = () => {
    warning('Low Balance', 'Consider adding more funds');
  };

  const handleInfo = () => {
    info('Processing', 'Your transaction is being processed');
  };

  return (
    <div>
      <button onClick={handleSuccess}>Success Toast</button>
      <button onClick={handleError}>Error Toast</button>
      <button onClick={handleWarning}>Warning Toast</button>
      <button onClick={handleInfo}>Info Toast</button>
    </div>
  );
}

Advanced Toast Usage

import { useToast } from 'interop-widget';

function AdvancedComponent() {
  const { addToast, removeToast, clearAllToasts } = useToast();

  const showCustomToast = () => {
    const toastId = addToast({
      title: 'Custom Toast',
      description: 'This is a custom toast with transaction hash',
      status: 'success',
      duration: 10000, // 10 seconds
      hash: '0x123...abc', // Transaction hash
      chain: chainInfo // Chain info for explorer link
    });

    // Manually remove after 5 seconds
    setTimeout(() => removeToast(toastId), 5000);
  };

  return (
    <div>
      <button onClick={showCustomToast}>Custom Toast</button>
      <button onClick={clearAllToasts}>Clear All Toasts</button>
    </div>
  );
}

Manual Toast Component (Not Recommended)

For advanced use cases, you can still use the Toast component directly:

import { Toast } from 'interop-widget';

function ManualToast() {
  const [showToast, setShowToast] = useState(false);

  return (
    <>
      <button onClick={() => setShowToast(true)}>Show Toast</button>
      <Toast 
        isOpen={showToast}
        onClose={() => setShowToast(false)}
        title="Manual Toast"
        description="This requires manual state management"
        status="info"
      />
    </>
  );
}

Theme Structure

The theme object has a simple structure:

interface Theme {
  color: {
    'primary-bg': string;
    'secondary-bg': string;
    'ternary-bg': string;
    'text-primary': string;
    'text-secondary': string;
    'text-tertiary': string;
  };
}

Default Theme

const defaultTheme = {
  color: {
    'primary-bg': '#ffffff',
    'secondary-bg': '#f8f9fa',
    'ternary-bg': '#e9ecef',
    'text-primary': '#212529',
    'text-secondary': '#6c757d',
    'text-tertiary': '#adb5bd',
  },
};

Examples

Dark Theme

const darkTheme = {
  color: {
    'primary-bg': '#1a1a1a',
    'secondary-bg': '#2d2d2d',
    'ternary-bg': '#404040',
    'text-primary': '#ffffff',
    'text-secondary': '#b3b3b3',
    'text-tertiary': '#808080',
  },
};

<InteropWidget theme={darkTheme} />

Light Theme

const lightTheme = {
  color: {
    'primary-bg': '#ffffff',
    'secondary-bg': '#f8f9fa',
    'ternary-bg': '#e9ecef',
    'text-primary': '#212529',
    'text-secondary': '#6c757d',
    'text-tertiary': '#adb5bd',
  },
};

<InteropWidget theme={lightTheme} />

Partial Theme (Override Only What You Need)

const partialTheme = {
  color: {
    'primary-bg': '#ff0000', // Only change primary background
  },
};

<InteropWidget theme={partialTheme} />

Configuration

Supported Chains

Currently, the widget supports the following chains:

Mainnet

• Base (Chain ID: 8453) - Base blockchain
• BNB Chain (Chain ID: 56) - Binance Smart Chain

Testnet

• Sepolia Base (Chain ID: 84532) - Base testnet
• BEVM (Chain ID: 11503) - BEVM testnet

Supported Tokens

Mainnet Tokens

• Base Chain:

  • CBBTC - Core Bitcoin (Contract: 0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf)

• BNB Chain:

  • BTCB - Bitcoin BEP2 (Contract: 0x7130d2A12B9BCbFAe4f2634d864A1Ee1Ce3Ead9c)

Testnet Tokens

• Sepolia Base:

  • CBBTC - Core Bitcoin (Contract: 0xfaeec4E06C3D0439d2ac55473b4a45758031f86B)

• BEVM:

  • WBTC - Wrapped Bitcoin (Contract: 0xff204e2681a6fa0e2c3fade68a1b28fb90e4fc5f)

Chain-Token Mapping

The widget enforces type-safe chain-token combinations:

type ChainTokenMapping = {
  "Sepolia Base": "CBBTC";
  "BEVM": "WBTC";
  "Base": "CBBTC";
  "BNB Chain": "BTCB";
};

API Reference

InteropWidget Props

Prop	Type	Default	Description
theme	Partial<Theme>	defaultTheme	Custom theme object
defaultRouteConfig	DefaultRouteConfig	undefined	Pre-configured route
network	'mainnet' | 'testnet'	'mainnet'	Network environment

DefaultRouteConfig

interface DefaultRouteConfig {
  fromChain: ChainName;
  fromToken: TokenName;
  toChain: ChainName;
  toToken: TokenName;
}