Interop Widget

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

Installation

npm install @persistenceone/interop-widget

Basic Usage

import { InteropWidget } from '@persistenceone/interop-widget';
import '@persistenceone/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 '@persistenceone/interop-widget';
import '@persistenceone/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 '@persistenceone/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 '@persistenceone/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 '@persistenceone/interop-widget';

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

Toast Component

import { Toast } from '@persistenceone/interop-widget';

<Toast 
  isOpen={showToast}
  onClose={() => setShowToast(false)}
  title="Success!"
  description="Transaction completed"
  status="success"
/>

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;
}