Styling Widget

Customizing the Swapper Finance Widget Appearance

Customizing the Widget's Appearance

The Swapper Finance Widget offers a flexible 3-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. Brand Theme (Medium Priority): Apply your primary and secondary brand colors to key elements like buttons, links, and accents.

3. Component Styles (Highest Priority): Exercise fine-grained control over the appearance of specific elements within the widget, such as background color, border radius, text colors, and button styles.

Styles from a higher priority level will override those from a lower one. For example, a primaryButtonBackground defined in componentStyles will take precedence over the button color derived from brandTheme or themeMode.

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:

// In your JavaScript when configuring the widget:

const yourIntegratorId = "xxxx"; // Your actual integrator ID
const IFRAME_BASE_URI = "https://app.swapper.finance";
const iframeElement = document.getElementById("swapperFinanceWidget"); // Assuming your iframe has this ID

const swapperConfig = {
  integratorId: yourIntegratorId,
  styles: { // <-- Add your styles object here
    themeMode: 'dark',
    brandTheme: {
      primaryColor: '#FF6B35', // Your primary brand color
    },
    componentStyles: {
      backgroundColor: "#444444"
    }
  }
};

// Serialize the styles object as JSON to be passed via URL
const queryParams = new URLSearchParams({
  integratorId: swapperConfig.integratorId,
  styles: JSON.stringify(swapperConfig.styles),
}).toString();

// Set the iframe source URL
if (iframeElement) {
  const iframeSrc = `${IFRAME_BASE_URI}?${queryParams}`;
  iframeElement.src = iframeSrc;
  console.log("Swapper Finance Widget: URL configured with query parameters.");
  console.log("Full URL:", iframeSrc);
} else {
  console.error("Swapper Finance Widget: Iframe element not found.");
}

Style Configuration Object (SwapperStyles)

The styles object you pass adheres to the following structure:

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

type ThemeMode = 'light' | 'dark';

type BrandTheme = {
  primaryColor?: string;    // Main brand color (buttons, links, accents)
  secondaryColor?: string;  // Secondary actions, highlights, less prominent elements
};

type ComponentStyles = {
  // Layout & General Appearance
  backgroundColor?: string;      // Overall background color of the widget
  width?: string;                // To set a specific width for the widget iframe container
  
  // Typography
  textColor?: string;            // Default text color for the widget content
  
  // Buttons
  primaryButtonBackground?: string;  // Background color for primary action buttons
  primaryButtonText?: string;        // Text color for primary action buttons
  secondaryButtonBackground?: string;// Background color for secondary action buttons
  secondaryButtonText?: string;      // Text color for secondary action buttons
  disabledButtonBackground?: string; // Background color for disabled buttons
  disabledButtonText?: string;       // Text color for disabled buttons
  
  // Status Indicators
  successColor?: string;         // Color for success messages and indicators
  warningColor?: string;         // Color for warning messages and indicators
  errorColor?: string;           // Color for error messages and indicators
};

Customization Levels & Examples

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

1. Theme Mode (themeMode)

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. Brand Theme (brandTheme)

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

• primaryColor: Your main brand color, used for primary calls to action and prominent accents.

• secondaryColor: A secondary color for less critical actions or highlights.

Example:

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

3. Component Styles (componentStyles)

For the most detailed control, use componentStyles. These allow you to override specific visual aspects of the widget.

Example:

javascript// For full customization
const swapperConfig = {
  integratorId: "YOUR_INTEGRATOR_ID",
  styles: {
    themeMode: 'light',
    brandTheme: {
      primaryColor: '#FF6B35',
      secondaryColor: '#004E89'
    },
    componentStyles: {
      backgroundColor: '#F8F9FA',         // Custom light grey background
      textColor: '#2C3E50',               // Custom text color
      primaryButtonBackground: '#E74C3C', // Override primary button color
      primaryButtonText: '#FFFFFF',       // White text on the custom primary button
      successColor: '#27AE60',            // Custom success color
      warningColor: '#F39C12',            // Custom warning color
      errorColor: '#E74C3C'               // Custom error color
    }
  }
};

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. Brand Theme Colors: Your specified primaryColor and secondaryColor. These will override relevant parts of the default theme.

3. Component Styles: Specific overrides are defined in componentStyles. These take the highest precedence and will override any conflicting styles from the brand theme or 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.