MPS Chatbot Widget

A standalone chatbot widget that third-party websites can embed via a single <script> tag.

Features

• Self-contained React application bundled into a single JS file
• Easy integration with any website
• Floating button mode (default) or embedded mode
• Customizable theming
• Style isolation (won't conflict with host site CSS)
• Native mobile support via WebView

Tech Stack

• React 19 with TypeScript
• Vite (library mode build)
• Emotion (CSS-in-JS for style isolation)
• lucide-react (icons)

Compatibility

Via CDN/Script Tag (Any Project)

When using the UMD bundle via <script> tag, the widget bundles its own React and renders in an isolated container. Your project's React version doesn't matter — this works with any framework (or no framework at all), including:

• Vanilla JavaScript/HTML
• jQuery
• Angular, Vue, Svelte
• Older React versions (14, 15, 16, etc.)

Via npm Import (React 18+ Required)

When importing as an ES module in a React project:

import '@mypatientspace/chatbot-widget';

You need React 18 or higher. The widget uses modern React features (hooks, Context API) that aren't available in older versions.

Installation

Via CDN (Recommended)

unpkg:

<script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>

jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>

Via npm

npm install @mypatientspace/chatbot-widget

Development

# Install dependencies
yarn install

# Start dev server (includes demo UI)
yarn dev

# Build for production
yarn build              # Builds both widget and demo
yarn build:widget       # Widget only
yarn build:demo         # Demo only

# Preview production build
yarn preview

Demo Widget

An embeddable demo page with configuration panel and live preview. Useful for testing and showcasing the widget.

Via CDN

<div id="chatbot-demo" style="height: 600px;"></div>
<script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-demo.umd.js"></script>
<script>
  ChatbotWidgetDemo.init({
    containerSelector: '#chatbot-demo',
    showJsonEditor: true,
    initialConfig: {
      headerTitle: 'My Healthcare Bot',
      theme: { colors: { primary: '#007bff' } }
    },
    onConfigChange: (config) => console.log('Config:', config)
  });
</script>

Demo API

ChatbotWidgetDemo.init(config);    // Initialize demo
ChatbotWidgetDemo.destroy();       // Remove demo
ChatbotWidgetDemo.update(config);  // Update configuration

Demo Configuration

Web Integration

Minimal Setup

<script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
<script>
  ChatbotWidget.init({
    apiEndpoint: 'https://your-api.com/chat',
    token: 'your-auth-token'
  });
</script>

Full Customization

<script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
<script>
  ChatbotWidget.init({
    apiEndpoint: 'https://your-api.com/chat',
    token: 'your-auth-token',
    headerTitle: 'Health Support',
    greeting: 'Hi! How can I help?',
    brandingText: 'Powered by MyCompany',
    headerIcon: '/logo.png',
    fabIcon: '/avatar.png',
    placeholder: 'Ask me anything...',
    position: 'bottom-left',
    quickActions: ['I need help', 'Book appointment'],
    theme: {
      // All color properties are optional - only set what you want to change
      colors: {
        // Main colors
        primary: '#ff6600',        // FAB button, links, main accent
        primaryDark: '#cc5200',    // Hover states
        secondary: '#2d3748',      // Header background
        accent: '#4299e1',         // Secondary accent
        accentLight: '#bee3f8',    // Light accent

        // Status colors
        success: '#48bb78',        // Success states
        info: '#4299e1',           // Info states
        error: '#f56565',          // Error states

        // Background colors
        background: '#ffffff',     // Chat window background
        surface: '#f7fafc',        // Input/card backgrounds

        // Text colors
        text: '#2d3748',           // Primary text
        textLight: '#718096',      // Secondary text, timestamps

        // Message bubbles
        userBubble: '#ff6600',     // User message background
        userBubbleText: '#ffffff', // User message text
        botBubble: '#edf2f7',      // Bot message background
        botBubbleText: '#2d3748',  // Bot message text

        // Borders
        border: '#e2e8f0',         // Border color
        borderLight: '#edf2f7',    // Light border

        // Other
        white: '#ffffff',          // White color
        recording: '#f56565',      // Voice recording indicator
      },

      // Typography and shape
      fontFamily: 'Inter, system-ui, sans-serif',
      borderRadius: '8px',
      shadow: '0 4px 12px rgba(0, 0, 0, 0.1)',
    }
  });
</script>

Via npm import

import '@mypatientspace/chatbot-widget';

ChatbotWidget.init({
  apiEndpoint: 'https://your-api.com/chat'
});

API Methods

ChatbotWidget.open();    // Open chat window
ChatbotWidget.close();   // Close chat window
ChatbotWidget.toggle();  // Toggle open/close
ChatbotWidget.destroy(); // Remove widget completely

Embedded Mode

By default, the widget displays as a floating button that opens a popup. You can also embed the chat directly inside any container on your page.

Using containerSelector

Embed the chat inside an existing element:

<div id="my-chat" style="width: 400px; height: 600px;"></div>

<script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
<script>
  ChatbotWidget.init({
    apiEndpoint: 'https://your-api.com/chat',
    containerSelector: '#my-chat'
  });
</script>

Using floatingMode

Enable floating mode with FAB button (classic chatbot style):

<script>
  ChatbotWidget.init({
    apiEndpoint: 'https://your-api.com/chat',
    floatingMode: true
  });
</script>

Comparison

Mobile Integration

Android (Kotlin)

class ChatActivity : AppCompatActivity() {
    private lateinit var webView: WebView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        webView = WebView(this).apply {
            settings.javaScriptEnabled = true
            settings.domStorageEnabled = true
            loadDataWithBaseURL(
                "https://your-domain.com",
                """
                <!DOCTYPE html>
                <html>
                <head>
                    <meta name="viewport" content="width=device-width, initial-scale=1">
                </head>
                <body style="margin:0;padding:0;">
                    <script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
                    <script>
                        ChatbotWidget.init({
                            apiEndpoint: 'https://your-api.com/chat'
                        });
                        ChatbotWidget.open();
                    </script>
                </body>
                </html>
                """.trimIndent(),
                "text/html", "UTF-8", null
            )
        }
        setContentView(webView)
    }
}

iOS (Swift)

import UIKit
import WebKit

class ChatViewController: UIViewController {
    var webView: WKWebView!

    override func viewDidLoad() {
        super.viewDidLoad()

        let config = WKWebViewConfiguration()
        config.preferences.javaScriptEnabled = true

        webView = WKWebView(frame: view.bounds, configuration: config)
        webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(webView)

        let html = """
        <!DOCTYPE html>
        <html>
        <head>
            <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
            <style>body { margin: 0; padding: 0; }</style>
        </head>
        <body>
            <script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
            <script>
                ChatbotWidget.init({
                    apiEndpoint: 'https://your-api.com/chat'
                });
                ChatbotWidget.open();
            </script>
        </body>
        </html>
        """

        webView.loadHTMLString(html, baseURL: URL(string: "https://your-domain.com"))
    }
}

React Native

import { WebView } from 'react-native-webview';

const ChatScreen = () => {
  const html = `
    <!DOCTYPE html>
    <html>
    <head>
        <meta name="viewport" content="width=device-width, initial-scale=1">
    </head>
    <body style="margin:0;padding:0;">
        <script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
        <script>
            ChatbotWidget.init({
                apiEndpoint: 'https://your-api.com/chat'
            });
            ChatbotWidget.open();
        </script>
    </body>
    </html>
  `;

  return (
    <WebView
      source={{ html }}
      javaScriptEnabled={true}
      domStorageEnabled={true}
    />
  );
};

Configuration Reference

All Options

Callbacks

Message Interface

interface Message {
  id: string;
  content: string;
  sender: 'user' | 'bot';
  timestamp: Date;
  status: 'sending' | 'sent' | 'error';
  audioUrl?: string;  // Base64 audio data URL for TTS playback
}

ThemeConfig Interface

interface ThemeConfig {
  colors?: Partial<ThemeColors>;  // Any subset of theme colors
  fontFamily?: string;
  borderRadius?: string;
  shadow?: string;
}

Available Theme Colors

Default Values

License

MIT