Styling Widget

Customizing the Swapper Finance Deposit Widget Appearance

Customizing the Widget's Appearance

The Swapper Finance Widget offers a flexible 2-tier styling system, allowing you to tailor its appearance to seamlessly match your platform's branding and design language. This system provides varying levels of customization, from simple theme selection to granular control over individual components.

Overview of the Styling System

The styling capabilities are organized into three distinct levels, applied in order of priority:

1. Theme Mode (Lowest Priority): Select a basic light or dark theme as a starting point.

2. Component Styles (Medium Priority): Apply your brand colors to key elements like buttons, links, and accents.

Styles from a higher priority level will override those from a lower one.

How to Apply Styles

Custom styles are passed to the Swapper Finance Widget through the styles object, similar to how the integratorId is provided.

Example of passing styles in swapperConfig:

// SDK-based example (no manual URL building)
import { SwapperIframe } from '@swapper-finance/deposit-sdk';

const yourIntegratorId = 'xxxx'; // Your actual integrator ID

const swapper = new SwapperIframe({
  container: '#swapperFinanceWidget', // or pass an HTMLElement
  integratorId: yourIntegratorId,
  // Required deposit params:
  dstChainId: '8453',                    // Destination chain ID (example: Base)
  dstTokenAddr: '0x...',                 // Destination token address (ERC-20)
  depositWalletAddress: '0x...',         // Wallet receiving deposits
  // Styling (same structure as before)
  styles: {
    themeMode: 'dark',
    componentStyles: {
      primaryColor: '#FF6B35',
      primaryBorderColor: '#FF6B35',
      accentColor: '#FF6B35',
      primaryTextColor: "#FFFFFF"
    }
  },
});

// Optionally update styles later
// swapper.updateStyles({ themeMode: 'light' });

Style Configuration Object (SwapperStyles)

The styles object you pass adheres to the following structure:

type SwapperStyles = {
  themeMode?: ThemeMode;
  componentStyles?: ComponentStyles;
};

type ThemeMode = 'light' | 'dark';

type ComponentStyles = {
  primaryColor?: string;    
  primaryBorderColor?: string;
  accentColor?: string;
  primaryTextColor?: string;
};

Customization Levels & Examples

Here’s how you can use each level of customization:

1. Theme Mode

This is the most basic level of customization.

• themeMode: 'light' (Default if not specified): Applies a light background with dark text.

• themeMode: 'dark': Applies a dark background with light text.

Example:

// To apply the dark theme
const swapperConfig = {
  integratorId: "YOUR_INTEGRATOR_ID",
  styles: {
    themeMode: 'dark'
  }
};

2. Component Styles

Define your core brand colors. These will influence the default styling of interactive elements like buttons and links, fitting them into your brand identity.

Example:

// To apply your brand colors with a light theme
const swapperConfig = {
  integratorId: "YOUR_INTEGRATOR_ID",
  styles: {
    themeMode: 'light', // Can be 'light' or 'dark'
    componentStyles: {
      primaryColor: '#FF6B35',      // Example: A vibrant orange
    }
  }
};

Style Application Hierarchy

To reiterate, styles are applied in the following sequence, with later styles overriding earlier ones:

1. Default Theme Styles: The widget's built-in light or dark theme defaults.

2. Component Styles: These will override relevant parts of the default theme.

Color Validation

• The SDK expects color values primarily as Hex strings (e.g., #fff, #FFFFFF, #FF6B35).

• If an invalid color format is provided for a property, it will likely be ignored, and a warning may be logged to the browser's console. The widget will fall back to the next valid style in the hierarchy.