@quickquerybot/widget v1.0.1

@quickquerybot/widget

A React component and JavaScript library for easily embedding the QuickQueryBot chat widget in your web applications.

Table of Contents

• Installation
• Quick Start
• Usage Methods
  • React Component
  • React Hook
  • JavaScript/TypeScript (Non-React)
• Framework Integration
  • Next.js
  • Create React App
  • Vite
  • Angular
  • Vue
• Configuration Options
• Customization Examples
• TypeScript Support
• API Reference
• Troubleshooting
• Development
• License

Installation

Install the package using npm or yarn:

# Using npm
npm install @quickquerybot/widget

# Using yarn
yarn add @quickquerybot/widget

# Using pnpm
pnpm add @quickquerybot/widget

Quick Start

The fastest way to add the chat widget to your React application is to use the ChatWidget component:

import { ChatWidget } from '@quickquerybot/widget';

function App() {
  return (
    <div>
      <h1>My Website</h1>
      
      {/* Add the chat widget anywhere in your component tree */}
      <ChatWidget 
        websiteId="your-website-id"
        primaryColor="#0070f3"
      />
    </div>
  );
}

export default App;

Usage Methods

React Component

The ChatWidget component is the recommended way to use the widget in React applications:

import { ChatWidget } from '@quickquerybot/widget';

function App() {
  return (
    <div>
      {/* The widget will be fixed-positioned at bottom-right by default */}
      <ChatWidget 
        websiteId="your-website-id"
        primaryColor="#0070f3"
        position="bottom-right"
        title="Customer Support"
        welcomeMessage="Hello! How can I assist you today?"
      />
    </div>
  );
}

React Hook

The hook approach is useful when you need more control or have specific initialization requirements:

import { useEffect } from 'react';
import { useChatWidget } from '@quickquerybot/widget';

function App() {
  // Initialize chat widget with configuration
  useChatWidget({
    websiteId: 'your-website-id',
    primaryColor: '#0070f3',
    welcomeMessage: 'Hello! How can I help you today?',
    // Only open during business hours
    position: new Date().getHours() < 17 ? 'bottom-right' : 'hidden'
  });
  
  return (
    <div>
      <h1>My Website</h1>
      {/* Widget is injected into the DOM automatically */}
    </div>
  );
}

JavaScript/TypeScript (Non-React)

For non-React applications or scenarios where you need full control over initialization:

import { initChatWidget } from '@quickquerybot/widget';

// Initialize the widget when you're ready
function setupChat() {
  initChatWidget({
    websiteId: 'your-website-id',
    primaryColor: '#0070f3',
    position: 'bottom-right'
  });
}

// Call on page load or after user interaction
document.addEventListener('DOMContentLoaded', setupChat);

// Or trigger based on user behavior
document.getElementById('help-button').addEventListener('click', () => {
  setupChat();
  // Optionally open the chat immediately
  window.__quickquerybot_open_chat?.();
});

Framework Integration

Next.js Integration

App Router (Next.js 13+)

Use the component in a client-side component:

'use client';

import { ChatWidget } from '@quickquerybot/widget';

export default function Layout({ children }) {
  return (
    <div>
      {children}
      <ChatWidget 
        websiteId="your-website-id"
        primaryColor="#0070f3"
      />
    </div>
  );
}

Pages Router

// In _app.js or a layout component
import { ChatWidget } from '@quickquerybot/widget';

function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <ChatWidget 
        websiteId="your-website-id"
        primaryColor="#0070f3"
      />
    </>
  );
}

export default MyApp;

Create React App

// In src/App.js or a layout component
import { ChatWidget } from '@quickquerybot/widget';

function App() {
  return (
    <div className="App">
      <header className="App-header">
        {/* Your app content */}
      </header>
      <ChatWidget 
        websiteId="your-website-id"
        primaryColor="#0070f3"
      />
    </div>
  );
}

export default App;

Vite

// In src/App.jsx or a layout component
import { ChatWidget } from '@quickquerybot/widget';

function App() {
  return (
    <div className="App">
      {/* Your app content */}
      <ChatWidget 
        websiteId="your-website-id"
        primaryColor="#0070f3"
      />
    </div>
  );
}

export default App;

Angular

For Angular applications, you'll need to use the widget.js script directly:

// In app.component.ts
import { Component, OnInit } from '@angular/core';
import { initChatWidget } from '@quickquerybot/widget';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent implements OnInit {
  ngOnInit() {
    initChatWidget({
      websiteId: 'your-website-id',
      primaryColor: '#0070f3',
    });
  }
}

Vue

For Vue applications, create a component to wrap the widget:

<!-- ChatWidget.vue -->
<template>
  <div></div> <!-- Widget is injected into DOM directly -->
</template>

<script>
import { initChatWidget } from '@quickquerybot/widget';

export default {
  name: 'ChatWidget',
  props: {
    websiteId: {
      type: String,
      required: true
    },
    primaryColor: {
      type: String,
      default: '#0070f3'
    },
    position: {
      type: String,
      default: 'bottom-right'
    }
  },
  mounted() {
    initChatWidget({
      websiteId: this.websiteId,
      primaryColor: this.primaryColor,
      position: this.position
    });
  }
}
</script>

Then use it in your app:

<!-- App.vue -->
<template>
  <div id="app">
    <!-- Your app content -->
    <ChatWidget websiteId="your-website-id" />
  </div>
</template>

<script>
import ChatWidget from './components/ChatWidget.vue';

export default {
  name: 'App',
  components: {
    ChatWidget
  }
}
</script>

Configuration Options

Customization Examples

Styling the Widget

import { ChatWidget } from '@quickquerybot/widget';

// Example with full styling options
<ChatWidget 
  websiteId="your-website-id"
  title="Product Support"
  welcomeMessage="Hi there! Need help with our product?"
  primaryColor="#4F46E5" // Indigo
  messageColor="#4F46E5" // User message bubbles
  botMessageColor="#F3F4F6" // Bot message bubbles
  position="bottom-right"
  inputPlaceholder="Ask a question..."
/>

Conditionally Showing the Widget

import { useState, useEffect } from 'react';
import { ChatWidget } from '@quickquerybot/widget';

function App() {
  const [showWidget, setShowWidget] = useState(false);
  
  // Show widget after 5 seconds
  useEffect(() => {
    const timer = setTimeout(() => {
      setShowWidget(true);
    }, 5000);
    
    return () => clearTimeout(timer);
  }, []);
  
  return (
    <div>
      <h1>My Website</h1>
      {showWidget && (
        <ChatWidget 
          websiteId="your-website-id"
          primaryColor="#0070f3"
        />
      )}
    </div>
  );
}

TypeScript Support

The package includes full TypeScript definitions. Import the types when needed:

import { ChatWidget, ChatWidgetProps } from '@quickquerybot/widget';

// You can use the ChatWidgetProps type for your own components
interface MyComponentProps {
  widgetConfig: ChatWidgetProps;
}

function MyComponent({ widgetConfig }: MyComponentProps) {
  return (
    <div>
      <ChatWidget {...widgetConfig} />
    </div>
  );
}

API Reference

ChatWidget Component

React component for embedding the chat widget.

import { ChatWidget } from '@quickquerybot/widget';

<ChatWidget 
  websiteId="your-website-id"
  // ... other props
/>

useChatWidget Hook

React hook for initializing the chat widget.

import { useChatWidget } from '@quickquerybot/widget';

function Component() {
  useChatWidget({
    websiteId: 'your-website-id',
    // ... other props
  });
  
  return <div>Your component</div>;
}

initChatWidget Function

Vanilla JavaScript function for initializing the chat widget.

import { initChatWidget } from '@quickquerybot/widget';

initChatWidget({
  websiteId: 'your-website-id',
  // ... other props
});

Troubleshooting

Widget Not Appearing

1. Verify your websiteId is correct and exists in your QuickQueryBot dashboard
2. Check browser console for errors
3. Ensure you're using a client-side component in Next.js (add 'use client' directive)
4. Verify the widget script is loading properly (check network tab)

Styling Issues

1. Make sure color values are valid CSS colors
2. For conflicts with your site CSS, try adjusting z-index:

<ChatWidget 
  websiteId="your-website-id"
  // Custom styling with higher z-index if needed
  customStyles={{
    container: { zIndex: 10000 }
  }}
/>

API Connection Issues

If the widget isn't connecting to your API:

1. Check the API endpoint URL
2. Verify CORS settings on your server
3. Check authentication requirements

Development

If you're contributing to this package:

1. Clone the repository
2. Install dependencies: npm install
3. Build the package: npm run build
4. Run tests: npm test

License

MIT