Router Widget SDK

A production-ready React component for cross-chain swaps that can be embedded in any React application. Supports EVM chains, Solana, Bitcoin, and Sui with flexible wallet integration options.

Table of Contents

• Installation
• Quick Start
• Wallet Integration
  • Internal Wallet Mode (Default)
  • External Wallet Mode (Dynamic.xyz)
  • Solana Support
• Configuration
• API Reference
• Examples
• TypeScript Support
• Styling
• Environment Variables
• Browser Support

Installation

npm install router-widget-sdk
# or
pnpm add router-widget-sdk
# or
yarn add router-widget-sdk

Peer Dependencies

The SDK requires React 18.3.1 or higher:

npm install react@^18.3.1 react-dom@^18.3.1

Quick Start

Basic Usage

import { RouterWidget } from 'router-widget-sdk';
import 'router-widget-sdk/styles.css';

function App() {
  return (
    <RouterWidget
      config={{
        theme: { mode: 'dark' },
        integrator: 'MyDApp',
      }}
    />
  );
}

With Initial State

<RouterWidget
  config={{
    initialState: {
      fromChainId: '1', // Ethereum
      fromTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
      toChainId: '137', // Polygon
      toTokenAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174', // USDC on Polygon
    },
    theme: { mode: 'dark' },
    integrator: 'MyDApp',
  }}
/>

Wallet Integration

The SDK supports multiple wallet integration modes:

Internal Wallet Mode (Default)

By default, the SDK provides its own wallet connection infrastructure:

• EVM Chains: Uses Wagmi with AppKit for wallet connection
• Solana: Uses @solana/wallet-adapter-react with built-in adapters
• Bitcoin/Sui: Placeholder support (external providers required)

// No additional setup needed - SDK handles everything
<RouterWidget config={{ theme: { mode: 'dark' } }} />

The SDK will:

• Show its own wallet connection modal
• Support all EVM wallets (MetaMask, WalletConnect, Coinbase, etc.)
• Support Solana wallets (Phantom, Solflare, Coinbase Wallet, etc.)
• Handle wallet connection/disconnection automatically

External Wallet Mode (Dynamic.xyz)

If your app already uses Dynamic.xyz or another wallet provider, the SDK will automatically detect and use it. The SDK detects external Wagmi/Solana contexts and delegates wallet connection to your provider. Provide the onConnectClick callback in the config to handle wallet connection UI.

See examples/nextjs-dynamic-provider for a complete implementation example.

Solana Support

The SDK includes full Solana wallet support. In internal mode, it automatically provides Solana wallet infrastructure supporting Phantom, Solflare, Coinbase Wallet, and any Wallet Standard-compatible wallet. For external mode with Dynamic, see the nextjs-dynamic-provider example for integration details.

Configuration

Component Props

RouterWidget

The main widget component accepts a single prop:

interface RouterWidgetProps {
  /**
   * Widget configuration object
   * All properties are optional
   */
  config?: WidgetConfig;
}

Example:

<RouterWidget config={widgetConfig} />

WidgetConfig Interface

Complete configuration interface with all available options:

interface WidgetConfig {
  // Theme configuration
  theme?: WidgetTheme;
  
  // Initial swap state
  initialState?: InitialState;
  
  // Integrator identifier
  integrator?: string;
  
  // Feature flags
  features?: FeatureFlags;
  
  // Selected routing nodes
  selectedNodes?: string[];
  
  // Wallet integration
  wallet?: WalletConfig;
  
  // Widget mode flag
  isWidget?: boolean;
  
  // Chain type restrictions
  chains?: ChainConfig;
  
  // Custom wallet providers (advanced)
  providers?: any[];
}

WidgetTheme

Theme configuration options:

interface WidgetTheme {
  /**
   * Theme mode
   * - 'light': Light theme
   * - 'dark': Dark theme (default)
   * - 'auto': Follows system preference
   * 
   * @default 'dark'
   */
  mode?: 'light' | 'dark' | 'auto';

  /**
   * Primary accent color (hex format)
   * Used for buttons, links, and highlights
   * 
   * @example '#e4357a'
   */
  primaryColor?: string;

  /**
   * Background color (hex format)
   * Main background color for the widget
   * 
   * @example '#0a0a0a'
   */
  backgroundColor?: string;

  /**
   * Primary text color (hex format)
   * Main text color for content
   * 
   * @example '#ffffff'
   */
  textColorPrimary?: string;

  /**
   * Secondary text color (hex format)
   * Used for labels, hints, and less important text
   * 
   * @example '#a0a0a0'
   */
  textColorSecondary?: string;

  /**
   * Muted background color (hex format)
   * Used for cards, inputs, and secondary backgrounds
   * 
   * @example '#1a1a1a'
   */
  mutedColor?: string;

  /**
   * Card border radius (CSS value)
   * Only applied when isWidget: true
   * 
   * @example '10px' | '0.5rem' | '0'
   */
  cardBorderRadius?: string;

  /**
   * Button border radius (CSS value)
   * Applied to all buttons in the widget
   * 
   * @example '4px' | '0.25rem' | '0'
   */
  buttonBorderRadius?: string;

  /**
   * Font family (CSS font-family value)
   * Applied to all text in the widget
   * 
   * @example 'Inter, sans-serif' | 'system-ui'
   */
  fontFamily?: string;
}

Example:

<RouterWidget
  config={{
    theme: {
      mode: 'dark',
      primaryColor: '#e4357a',
      backgroundColor: '#0a0a0a',
      textColorPrimary: '#ffffff',
      textColorSecondary: '#a0a0a0',
      mutedColor: '#1a1a1a',
      cardBorderRadius: '10px', // Only applied when isWidget: true
      buttonBorderRadius: '4px',
      fontFamily: 'Inter, sans-serif',
    },
  }}
/>

InitialState

Pre-configure the swap interface with initial values:

interface InitialState {
  /**
   * Source chain ID
   * Chain ID of the source chain (e.g., '1' for Ethereum, '137' for Polygon)
   * 
   * @example '1' | '137' | '8453'
   */
  fromChainId?: string;

  /**
   * Source token address
   * Contract address of the source token
   * Use 'native' or '0x0000000000000000000000000000000000000000' for native token
   * 
   * @example '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' (USDC)
   */
  fromTokenAddress?: string;

  /**
   * Destination chain ID
   * Chain ID of the destination chain
   * 
   * @example '137' | '42161'
   */
  toChainId?: string;

  /**
   * Destination token address
   * Contract address of the destination token
   * 
   * @example '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174' (USDC on Polygon)
   */
  toTokenAddress?: string;
}

Example:

<RouterWidget
  config={{
    initialState: {
      fromChainId: '1', // Ethereum
      fromTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
      toChainId: '137', // Polygon
      toTokenAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174', // USDC on Polygon
    },
  }}
/>

FeatureFlags

Control widget features and UI elements:

interface FeatureFlags {
  /**
   * Show header in the swap interface
   * 
   * @default true
   */
  showHeader?: boolean;

  /**
   * Disable source chain/token selection
   * When true, users cannot change the source chain or token
   * 
   * @default false
   */
  isSrcDisabled?: boolean;

  /**
   * Disable destination chain/token selection
   * When true, users cannot change the destination chain or token
   * 
   * @default false
   */
  isDestDisabled?: boolean;
}

Example:

<RouterWidget
  config={{
    features: {
      showHeader: true,
      isSrcDisabled: false,
      isDestDisabled: false,
    },
  }}
/>

WalletConfig

Wallet integration callbacks for external wallet providers:

interface WalletConfig {
  /**
   * Called when user clicks "CONNECT WALLET" button
   * Only triggered when external wallet provider is detected (e.g., Dynamic.xyz)
   * 
   * Use this to open your app's wallet connection UI
   * 
   * @example
   * wallet: {
   *   onConnectClick: () => {
   *     setShowAuthFlow(true); // Open Dynamic auth flow
   *   },
   * }
   */
  onConnectClick?: () => void;
}

Example:

<RouterWidget
  config={{
    wallet: {
      onConnectClick: () => {
        // Open your wallet connection modal
        setShowAuthFlow(true);
      },
    },
  }}
/>

Other Config Options

interface WidgetConfig {
  /**
   * Integrator identifier
   * Used for analytics and tracking
   * 
   * @example 'MyDApp' | 'MyCompany'
   */
  integrator?: string;

  /**
   * Selected routing nodes/bridges
   * Array of node IDs to use for routing
   * If not provided, default nodes are used
   * 
   * @example ['router', 'stargate', 'hop']
   */
  selectedNodes?: string[];

  /**
   * Widget mode flag
   * When true:
   * - Applies widget-specific styling (rounded corners, etc.)
   * - Shows wallet header in widget mode
   * - Optimizes for embedded use case
   * 
   * When false:
   * - Uses flat design (no rounded corners)
   * - Hides widget-specific UI elements
   * - Optimizes for full-page use case
   * 
   * @default false
   */
  isWidget?: boolean;
}

Complete Configuration Example

<RouterWidget
  config={{
    // Theme
    theme: {
      mode: 'dark',
      primaryColor: '#e4357a',
      backgroundColor: '#0a0a0a',
      textColorPrimary: '#ffffff',
      textColorSecondary: '#a0a0a0',
      mutedColor: '#1a1a1a',
      cardBorderRadius: '10px',
      buttonBorderRadius: '4px',
      fontFamily: 'Inter, sans-serif',
    },

    // Initial state
    initialState: {
      fromChainId: '1',
      fromTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
      toChainId: '137',
      toTokenAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174',
    },

    // Features
    features: {
      showHeader: true,
      isSrcDisabled: false,
      isDestDisabled: false,
    },

    // Wallet integration
    wallet: {
      onConnectClick: () => {
        setShowAuthFlow(true);
      },
    },


    // Other options
    integrator: 'MyDApp',
    selectedNodes: ['router', 'stargate'],
    isWidget: true,
  }}
/>

API Reference

Components

RouterWidget

Main widget component. Renders the complete swap interface with all necessary providers.

Props:

interface RouterWidgetProps {
  /**
   * Widget configuration object
   * All properties are optional
   * 
   * @see WidgetConfig for complete configuration options
   */
  config?: WidgetConfig;
}

Exported Types

The SDK exports the following TypeScript types:

// Main exports
import { RouterWidget, type WidgetConfig } from 'router-widget-sdk';

// Default export
import RouterWidget from 'router-widget-sdk';

Public API Exports:

// Component
export { RouterWidget };
export default RouterWidget;

// Configuration type
export type { WidgetConfig };

Note: The WidgetConfig type includes all nested types (WidgetTheme, InitialState, FeatureFlags, WalletConfig, ChainConfig) as documented in the Configuration section above. These nested types are part of the WidgetConfig interface and don't need to be imported separately.

Examples

Basic Next.js Example

// app/page.tsx
'use client';

import { RouterWidget } from 'router-widget-sdk';
import 'router-widget-sdk/styles.css';

export default function Home() {
  return (
    <main>
      <RouterWidget
        config={{
          theme: { mode: 'dark' },
          integrator: 'MyNextJSApp',
        }}
      />
    </main>
  );
}

With Dynamic.xyz

See examples/nextjs-dynamic-provider for a complete example with:

• Dynamic.xyz wallet integration
• EVM and Solana support
• External wallet context detection

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import { RouterWidget, type WidgetConfig } from 'router-widget-sdk';

const config: WidgetConfig = {
  theme: { mode: 'dark' },
  integrator: 'MyDApp',
};

<RouterWidget config={config} />

Styling

Default Styles

Import the CSS file to get default styles:

import 'router-widget-sdk/styles.css';

Custom Styling

Override styles using CSS variables:

.router-widget {
  --primary: #e4357a;
  --background: #0a0a0a;
  --foreground: #ffffff;
  --muted: #1a1a1a;
}

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Features

• ✅ Multi-Chain Support: EVM, Solana, Bitcoin, Sui
• ✅ Flexible Wallet Integration: Internal or external wallet providers
• ✅ Real-time Quotes: Automatic quote fetching and refresh
• ✅ Customizable Themes: Light, dark, or custom colors
• ✅ TypeScript: Full type definitions included
• ✅ Responsive: Works on desktop and mobile
• ✅ Production Ready: Battle-tested and optimized

Contributing

Contributions are welcome! Please see our contributing guidelines.

License

MIT

Support

For issues and questions:

• GitHub Issues: router-protocol/blinq-ui
• Documentation: Router Protocol Docs