🎨 Color System

The Finder-v2 widget implements a flexible color theming system that allows customization to match your brand. The system uses CSS custom properties that can be overridden while maintaining consistent naming conventions.

Primary Brand Color Classes

The primary brand color is the main accent color used throughout the widget for interactive elements, highlights, and brand-specific styling. These classes adapt to your configured primary color.

Opacity Variants

Use opacity modifiers for subtle backgrounds and overlays:

Additional Color Classes

Usage Examples

OE vs Aftermarket Distinction

<!-- OE Option with primary color -->
<div class="border border-primary-color bg-primary-color/10 p-4 rounded">
  <span class="text-primary-color font-semibold">Original Equipment</span>
  <!-- content -->
</div>

<!-- Aftermarket Option with secondary color -->
<div class="border border-secondary-color hover:bg-secondary-color/10 p-4 rounded">
  <span class="text-secondary-color font-semibold">Aftermarket</span>
  <!-- content -->
</div>

Interactive Elements

<!-- Primary button -->
<button class="bg-primary-color text-white hover:bg-primary-color/90 px-4 py-2 rounded">
  Search
</button>

<!-- Secondary button -->
<button class="border border-primary-color text-primary-color hover:bg-primary-color/10 px-4 py-2 rounded">
  Clear
</button>

<!-- Link with primary color -->
<a href="#" class="text-primary-color hover:text-primary-color/80 underline">
  View Details
</a>

Badges and Labels

<!-- OE Badge -->
<span class="inline-flex px-2 py-1 text-xs font-medium rounded-full bg-primary-color/20 text-primary-color">
  OE
</span>

<!-- Aftermarket Badge -->
<span class="inline-flex px-2 py-1 text-xs font-medium rounded-full bg-secondary-color/20 text-secondary-color">
  AM
</span>

<!-- Feature Badge -->
<span class="inline-flex px-2 py-1 text-xs font-medium rounded-full bg-accent-color/20 text-accent-color">
  Winter
</span>

Cards with Hover Effects

<div class="bg-background-color border border-secondary-color hover:border-primary-color hover:shadow-lg transition-all duration-300 p-4 rounded-lg">
  <h3 class="text-main-color font-semibold">17" Wheel Option</h3>
  <p class="text-secondary-color">215/55R17 - 7Jx17 ET45</p>
  <div class="mt-2">
    <span class="text-primary-color font-medium">View Details →</span>
  </div>
</div>

Complete Color System Example

<div class="widget-container">
  <!-- Header with primary accent -->
  <header class="border-b-2 border-primary-color pb-4 mb-6">
    <h1 class="text-2xl font-bold text-main-color">Wheel Finder Results</h1>
    <p class="text-secondary-color">Found 3 options for your vehicle</p>
  </header>
  
  <!-- Results grid -->
  <div class="grid gap-4">
    <!-- OE Option Card -->
    <div class="bg-primary-color/5 border-2 border-primary-color rounded-lg p-6">
      <div class="flex justify-between items-start mb-4">
        <h3 class="text-lg font-semibold text-main-color">Factory Standard</h3>
        <span class="bg-primary-color text-white px-3 py-1 rounded-full text-sm font-medium">
          OE
        </span>
      </div>
      
      <div class="space-y-2">
        <div class="flex justify-between">
          <span class="text-secondary-color">Tire:</span>
          <span class="text-main-color font-medium">215/55R17</span>
        </div>
        <div class="flex justify-between">
          <span class="text-secondary-color">Rim:</span>
          <span class="text-main-color font-medium">7Jx17 ET45</span>
        </div>
      </div>
      
      <button class="mt-4 w-full bg-primary-color hover:bg-primary-color/90 text-white py-2 rounded-lg transition-colors">
        Select This Option
      </button>
    </div>
    
    <!-- Aftermarket Option Card -->
    <div class="bg-background-color border border-secondary-color hover:border-primary-color rounded-lg p-6 transition-colors">
      <div class="flex justify-between items-start mb-4">
        <h3 class="text-lg font-semibold text-main-color">Performance Upgrade</h3>
        <span class="bg-accent-color/20 text-accent-color px-3 py-1 rounded-full text-sm font-medium">
          AM
        </span>
      </div>
      
      <div class="space-y-2">
        <div class="flex justify-between">
          <span class="text-secondary-color">Tire:</span>
          <span class="text-main-color font-medium">225/50R18</span>
        </div>
        <div class="flex justify-between">
          <span class="text-secondary-color">Rim:</span>
          <span class="text-main-color font-medium">8Jx18 ET40</span>
        </div>
      </div>
      
      <button class="mt-4 w-full border border-primary-color text-primary-color hover:bg-primary-color/10 py-2 rounded-lg transition-colors">
        View Details
      </button>
    </div>
  </div>
</div>

📖 API Reference

Widget Creation

// Basic widget creation
var widget = WheelSizeWidgets.create('#container-id', {
  uuid: 'your-widget-uuid',
  type: 'finder-v2',
  // Optional configuration
  config: {
    theme: 'light',
    language: 'en',
    // ... other config options
  }
});

// Alternative: Use existing iframe
var widget = WheelSizeWidgets.create('#existing-iframe-id');

Event Handling Methods

// Subscribe to an event
widget.on('event-name', function(eventData) {
  console.log('Event received:', eventData);
});

// Unsubscribe from an event
widget.off('event-name', callbackFunction);

// One-time event listener
widget.once('ready:window', function(eventData) {
  console.log('Widget is ready (fires once)');
});

Widget Methods

Configuration Options

💡 Complete Integration Examples

Basic Integration

<!DOCTYPE html>
<html>
<head>
  <title>Finder-v2 Widget Integration</title>
</head>
<body>
  <!-- Widget container -->
  <div id="wheel-finder"></div>
  
  <!-- Load widget API -->
  <script src="//services.wheel-size.com/static/widget/code/local/ws-widget.js"></script>
  
  <script>
    // Create widget when DOM is ready
    document.addEventListener('DOMContentLoaded', function() {
      var widget = WheelSizeWidgets.create('#wheel-finder', {
        uuid: 'your-widget-uuid',
        type: 'finder-v2'
      });
      
      // Listen for widget ready
      widget.on('ready:window', function() {
        console.log('Widget is ready for interaction');
      });
      
      // Track user selections
      widget.on('change:make', function(e) {
        console.log('User selected make:', e.data.value.title);
      });
      
      widget.on('change:model', function(e) {
        console.log('User selected model:', e.data.value.title);
      });
      
      // Handle search results
      widget.on('results:display', function(e) {
        console.log('Results displayed:', e.data.results_count);
        // Send to analytics, update page, etc.
      });
    });
  </script>
</body>
</html>

Advanced Integration with Analytics

<script>
document.addEventListener('DOMContentLoaded', function() {
  var widget = WheelSizeWidgets.create('#wheel-finder', {
    uuid: 'your-widget-uuid',
    type: 'finder-v2',
    language: 'en',
    theme: 'light'
  });
  
  // Analytics tracking
  function trackEvent(action, label, value) {
    if (typeof gtag !== 'undefined') {
      gtag('event', action, {
        'event_category': 'WheelFinder',
        'event_label': label,
        'value': value
      });
    }
  }
  
  // Track widget initialization
  widget.on('ready:window', function() {
    trackEvent('widget_loaded', 'finder-v2', 1);
  });
  
  // Track user journey
  var selectionPath = [];
  
  ['year', 'make', 'model', 'generation', 'modification'].forEach(function(field) {
    widget.on('change:' + field, function(e) {
      selectionPath.push({
        field: field,
        value: e.data.value.slug,
        title: e.data.value.title
      });
      
      trackEvent('selection_made', field, selectionPath.length);
    });
  });
  
  // Track search events
  widget.on('search:start', function(e) {
    trackEvent('search_initiated', 'vehicle_search', 1);
    console.log('Search path:', selectionPath);
  });
  
  widget.on('search:complete', function(e) {
    trackEvent('search_completed', 'success', 1);
  });
  
  widget.on('search:error', function(e) {
    trackEvent('search_failed', e.data.error_message, 0);
    console.error('Search error:', e.data.error_message);
  });
  
  // Track results interaction
  widget.on('results:display', function(e) {
    var vehicle = e.data.context.selections;
    var vehicleString = [
      vehicle.year,
      vehicle.make,
      vehicle.model,
      vehicle.generation,
      vehicle.modification
    ].filter(Boolean).join(' / ');
    
    trackEvent('results_shown', vehicleString, e.data.results_count);
    
    // Update page title or breadcrumb
    document.title = 'Wheels for ' + vehicleString;
    
    // Show additional content based on results
    if (e.data.results_count > 0) {
      document.getElementById('related-products').style.display = 'block';
    }
  });
});
</script>

Error Handling and Fallbacks

document.addEventListener('DOMContentLoaded', function() {
  var widgetContainer = document.getElementById('wheel-finder');
  var errorContainer = document.getElementById('widget-error');
  var loadingIndicator = document.getElementById('widget-loading');
  
  try {
    var widget = WheelSizeWidgets.create('#wheel-finder', {
      uuid: 'your-widget-uuid',
      type: 'finder-v2'
    });
    
    // Set loading timeout
    var loadTimeout = setTimeout(function() {
      loadingIndicator.style.display = 'none';
      errorContainer.innerHTML = 'Widget is taking longer than expected to load...';
      errorContainer.style.display = 'block';
    }, 10000); // 10 second timeout
    
    // Clear timeout on successful load
    widget.on('ready:window', function() {
      clearTimeout(loadTimeout);
      loadingIndicator.style.display = 'none';
      console.log('Widget loaded successfully');
    });
    
    // Handle search errors
    widget.on('search:error', function(e) {
      console.error('Search error:', e.data.error_message);
      
      // Display user-friendly error message
      var userMessage = 'Unable to load results. Please try again.';
      
      if (e.data.error_message.includes('network')) {
        userMessage = 'Connection error. Please check your internet connection.';
      } else if (e.data.error_message.includes('timeout')) {
        userMessage = 'Request timed out. Please try again.';
      }
      
      // Show error notification
      showNotification(userMessage, 'error');
    });
    
    // Handle no results scenario
    widget.on('results:display', function(e) {
      if (e.data.results_count === 0) {
        showNotification('No wheel options found for this vehicle.', 'info');
        // Optionally show alternative suggestions
        showAlternativeSuggestions(e.data.context.selections);
      }
    });
    
  } catch (error) {
    console.error('Failed to initialize widget:', error);
    loadingIndicator.style.display = 'none';
    errorContainer.innerHTML = 'Unable to load the wheel finder. Please refresh the page.';
    errorContainer.style.display = 'block';
  }
});

function showNotification(message, type) {
  // Implementation of notification display
  var notification = document.createElement('div');
  notification.className = 'notification notification-' + type;
  notification.textContent = message;
  document.body.appendChild(notification);
  
  setTimeout(function() {
    notification.remove();
  }, 5000);
}

function showAlternativeSuggestions(selections) {
  // Implementation to show alternative vehicle suggestions
  console.log('Show alternatives for:', selections);
}

Finder-v2 Widget Documentation • Version 2.0 •