Theming

The useLoyalty Widget is fully customizable to match your brand. This guide covers all theming options from basic colors to advanced CSS customization.

Basic Theming

Pass a theme object during initialization:

UseLoyaltyWidget.init({
  ...auth,
  theme: {
    primaryColor: '#2563eb',
    backgroundColor: '#ffffff',
    textColor: '#0f172a',
    position: 'right'
  }
});

Theme Options

Colors

Option	Default	Description
`primaryColor`	`#6366f1`	Buttons, links, active states
`backgroundColor`	`#ffffff`	Main background
`textColor`	`#1e293b`	Primary text

theme: {
  primaryColor: '#10b981',    // Green buttons
  backgroundColor: '#f8fafc', // Light gray background
  textColor: '#334155'        // Dark gray text
}

Typography

theme: {
  fontFamily: '"Inter", system-ui, -apple-system, sans-serif'
}

Position

Control where the launcher button appears:

theme: {
  position: 'right'  // Default - bottom right corner
}

theme: {
  position: 'left'   // Bottom left corner
}

Border Radius

theme: {
  borderRadius: '16px'  // Default - rounded corners
}

theme: {
  borderRadius: '0'     // Square corners
}

theme: {
  borderRadius: '24px'  // Extra rounded
}

Launcher Button

Customize the floating trigger button:

theme: {
  launcher: {
    displayMode: 'floating', // 'floating' (default) or 'custom' (no button)
    variant: 'icon-only',    // 'icon-only' or 'icon-text'
    icon: 'gift',            // 'gift', 'star', 'coin', 'award'
    text: 'Rewards',         // Label for 'icon-text' variant
    pulse: false,            // Attention-grabbing pulse animation
    size: 56,                // Button diameter in pixels
    offset: {
      x: 20,                 // Distance from edge
      y: 20                  // Distance from bottom
    }
  }
}

Launcher Examples

// Icon with text label
theme: {
  launcher: {
    variant: 'icon-text',
    icon: 'star',
    text: 'Earn Points',
    pulse: true
  }
}

// Custom trigger (no floating button)
theme: {
  launcher: {
    displayMode: 'custom'
  }
}
// Then use: UseLoyaltyWidget.open() from your own buttons

Feature Visibility

Hide specific features:

theme: {
  hideQuests: false,   // Show/hide Games tab
  hidePromo: false,    // Show/hide promo code input
  hideBadges: false,   // Show/hide badges section
  hideRefer: false     // Show/hide Referral tab
}

CSS Variables

The widget uses CSS custom properties that you can override:

/* Add to your stylesheet */
.gw-root {
  /* Primary colors */
  --gw-primary: #6366f1;
  --gw-primary-light: rgba(99, 102, 241, 0.1);
  --gw-primary-hover: #4f46e5;

  /* Backgrounds */
  --gw-bg: #ffffff;
  --gw-bg-secondary: #f8fafc;
  --gw-bg-tertiary: #f1f5f9;

  /* Text */
  --gw-text: #1e293b;
  --gw-text-secondary: #64748b;
  --gw-text-muted: #94a3b8;

  /* Borders & Shadows */
  --gw-border: #e2e8f0;
  --gw-radius: 16px;
  --gw-radius-sm: 10px;
  --gw-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);

  /* Status colors */
  --gw-success: #22c55e;
  --gw-warning: #f59e0b;
  --gw-error: #ef4444;
}

Theme Presets

Light Theme (Default)

theme: {
  primaryColor: '#6366f1',
  backgroundColor: '#ffffff',
  textColor: '#1e293b'
}

Dark Theme

theme: {
  primaryColor: '#818cf8',
  backgroundColor: '#1e293b',
  textColor: '#f1f5f9'
}

Brand Colors

// Blue brand
theme: {
  primaryColor: '#2563eb',
  backgroundColor: '#eff6ff',
  textColor: '#1e3a8a'
}

// Green brand
theme: {
  primaryColor: '#10b981',
  backgroundColor: '#ecfdf5',
  textColor: '#064e3b'
}

// Purple brand
theme: {
  primaryColor: '#8b5cf6',
  backgroundColor: '#f5f3ff',
  textColor: '#4c1d95'
}

// Orange brand
theme: {
  primaryColor: '#f97316',
  backgroundColor: '#fff7ed',
  textColor: '#7c2d12'
}

Advanced CSS Customization

Target specific widget elements:

/* Launcher button */
.gw-launcher {
  box-shadow: 0 4px 14px rgba(0, 0, 0, 0.15);
}

/* Widget drawer */
.gw-drawer {
  max-width: 400px;
}

/* Header */
.gw-header {
  border-bottom: 1px solid var(--gw-border);
}

/* Profile bar */
.gw-profile-bar {
  padding: 16px;
}

/* Tab navigation */
.gw-tabs {
  gap: 8px;
}

.gw-tab-btn.active {
  font-weight: 600;
}

/* Reward cards */
.gw-card {
  border-radius: 12px;
  transition: transform 0.2s;
}

.gw-card:hover {
  transform: translateY(-2px);
}

/* Buttons */
.gw-btn-primary {
  font-weight: 600;
  text-transform: uppercase;
  letter-spacing: 0.5px;
}

/* Badges */
.gw-badge.earned {
  opacity: 1;
}

.gw-badge.locked {
  opacity: 0.5;
  filter: grayscale(1);
}

Responsive Behavior

The widget automatically adapts to mobile screens:

/* Mobile breakpoint at 480px */
@media (max-width: 480px) {
  .gw-drawer {
    width: 100%;
    height: 100%;
    border-radius: 0;
  }

  .gw-launcher {
    bottom: 16px;
    right: 16px;
  }
}

Override mobile styles:

@media (max-width: 480px) {
  .gw-drawer {
    /* Custom mobile styles */
    height: 80vh;
    border-radius: 16px 16px 0 0;
  }
}

Dynamic Theming

Change theme at runtime based on user preferences:

// Initialize with default theme
const widget = UseLoyaltyWidget.init({
  ...auth,
  theme: lightTheme
});

// Toggle dark mode
document.querySelector('#dark-mode-toggle').addEventListener('click', () => {
  const isDark = document.body.classList.toggle('dark');

  // Reinitialize with new theme
  UseLoyaltyWidget.destroy();
  UseLoyaltyWidget.init({
    ...auth,
    theme: isDark ? darkTheme : lightTheme
  });
});

CSS Class Reference

Class	Element
`.gw-root`	Root container
`.gw-launcher`	Floating button
`.gw-launcher-text`	Launcher with text label (icon-text variant)
`.gw-launcher-pulse`	Launcher with pulse animation
`.gw-launcher-label`	Text label inside launcher
`.gw-drawer`	Main widget panel
`.gw-header`	Top header bar
`.gw-profile-bar`	Profile section
`.gw-tabs`	Tab navigation
`.gw-tab-btn`	Individual tab button
`.gw-content`	Scrollable content area
`.gw-cards-grid`	Card layout grid
`.gw-card`	Individual card
`.gw-btn`	Button base class
`.gw-btn-primary`	Primary action button
`.gw-badge`	Badge display
`.gw-multiplier-banner`	Active multiplier banner
`.gw-achievement-modal`	Achievement popup

Best Practices

1. Match Your Brand

Use your brand's primary color for primaryColor:

theme: {
  primaryColor: '#your-brand-color'
}

2. Ensure Contrast

Make sure text is readable against backgrounds:

// Good contrast
theme: {
  backgroundColor: '#ffffff',
  textColor: '#1e293b'
}

// Poor contrast - avoid
theme: {
  backgroundColor: '#f0f0f0',
  textColor: '#a0a0a0'
}

3. Test on Mobile

Always test your theme on mobile devices:

// Consider touch targets
theme: {
  launcher: {
    size: 56  // Minimum 44px for touch
  }
}

4. Use System Fonts

For faster loading, use system fonts:

theme: {
  fontFamily: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif'
}

Theming

On this page