leadforward/widget-react

React component for embedding Leadforward feedback widget in your React applications.

Preview

Installation

npm install leadforward/widget-react

Usage

import { LeadForwardWidget } from 'leadforward/widget-react';

function App() {
  return (
    <div>
      {/* Your app content */}
      
      <LeadForwardWidget 
        config={{
          projectId: 'your-project-id',
          email: '[email protected]', // optional - can be set later with setEmail()
          position: 'bottom-right', // optional
          theme: 'auto', // optional
          primaryColor: '#6366f1', // optional
        }}
      />
    </div>
  );
}

Usage without initial email

You can also initialize the widget without an email and set it later:

import { LeadForwardWidget, setEmail } from 'leadforward/widget-react';

function App() {
  // Initialize widget without email
  return (
    <div>
      <LeadForwardWidget 
        config={{
          projectId: 'your-project-id',
          // No email provided initially
          position: 'bottom-right',
          theme: 'auto',
          primaryColor: '#6366f1',
        }}
      />
    </div>
  );
}

// Later, when user logs in:
// setEmail('[email protected]');

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | projectId | string | required | Your Leadforward project ID | | email | string | undefined | User's email address for feedback attribution (can be set later with setEmail()) | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | 'bottom-right' | Widget position on screen | | theme | 'light' \| 'dark' \| 'auto' | 'auto' | Widget theme | | primaryColor | string | '#6366f1' | Primary color for buttons and accents | | hideRoadmap | boolean | false | Hide the "View Roadmap" button | | hideBugReport | boolean | false | Hide the "Bug Report" option | | hideInPaths | string[] | [] | Array of URL paths where the widget should be hidden | | customLabels | object | {} | Custom labels for buttons | | apiBase | string | https://leadforward.one | API base URL (for custom deployments) |

Dynamic Email Setting

If you need to set the user's email dynamically (e.g., after user login), you can import and use the email management functions directly from the package:

import { setEmail, clearEmail, getEmail } from 'leadforward/widget-react';

// After user logs in
setEmail('[email protected]');

// To clear the email (e.g., after logout)
clearEmail();

// To get the current email
const currentEmail = getEmail();

TypeScript Support

The email management functions are fully typed and provide excellent TypeScript support:

import { setEmail, clearEmail, getEmail } from 'leadforward/widget-react';

// All functions are properly typed
setEmail('[email protected]'); // (email: string) => void
clearEmail(); // () => void
const email: string = getEmail(); // () => string

Example: Integration with Authentication

Here's a complete example showing how to integrate the widget with user authentication:

import React, { useEffect, useState } from 'react';
import { LeadForwardWidget, setEmail, clearEmail } from 'leadforward/widget-react';

function App() {
  const [user, setUser] = useState(null);

  useEffect(() => {
    // When user logs in
    if (user?.email) {
      setEmail(user.email);
    } else {
      // When user logs out
      clearEmail();
    }
  }, [user]);

  return (
    <div>
      {/* Your app content */}
      
      <LeadForwardWidget 
        config={{
          projectId: 'your-project-id',
          // No initial email - will be set dynamically after login
          position: 'bottom-right',
          theme: 'auto',
          primaryColor: '#6366f1',
        }}
      />
    </div>
  );
}

Custom Labels

You can customize the text displayed on buttons:

<LeadForwardWidget 
  config={{
    projectId: 'your-project-id',
    email: '[email protected]',
    customLabels: {
      suggestFeature: 'Request Feature',
      reportBug: 'Report Issue',
      generalFeedback: 'Send Feedback',
      viewRoadmap: 'Product Roadmap'
    }
  }}
/>

Hiding Widget on Specific Paths

You can hide the widget on specific URL paths using the hideInPaths option:

<LeadForwardWidget 
  config={{
    projectId: 'your-project-id',
    email: '[email protected]',
    hideInPaths: [
      '/admin',           // Hide on exact path
      '/dashboard/*',     // Hide on all dashboard routes
      '/checkout',        // Hide on checkout page
      '/settings/*',      // Hide on all settings routes
      '/privacy-policy'   // Hide on privacy policy page
    ]
  }}
/>

The hideInPaths option supports:

• Exact matching: /admin will only hide the widget on exactly /admin
• Wildcard matching: /dashboard/* will hide the widget on /dashboard, /dashboard/users, /dashboard/settings, etc.
• Dynamic updates: The widget automatically shows/hides when navigating between pages
• SPA compatibility: Works with single-page applications that use history.pushState or history.replaceState

TypeScript

This package includes TypeScript definitions. The main types are:

import type { LeadForwardConfig } from 'leadforward/widget-react';

const config: LeadForwardConfig = {
  projectId: 'your-project-id',
  // email is optional - can be set later with setEmail()
  position: 'bottom-right',
  theme: 'auto',
  primaryColor: '#6366f1',
  hideInPaths: ['/admin', '/checkout/*']
};

// Or with email provided initially
const configWithEmail: LeadForwardConfig = {
  projectId: 'your-project-id',
  email: '[email protected]',
  position: 'bottom-right',
  theme: 'auto',
  primaryColor: '#6366f1',
  hideInPaths: []
};

License

MIT