MorphChat

A modern, highly customizable React chat widget component with TypeScript support, featuring OpenAI integration and seamless website integration without style conflicts.

This project was developed as a part of a role application process to Eloquent AI.

🚀 Click here to open the Live Demo

🔗 Click here to see the lib page in NPM

📄 Introduction

MorphChat is a powerful React library that provides a fully customizable chat widget for your website. Built with TypeScript and modern React patterns, it offers seamless integration with OpenAI's API while maintaining complete style isolation to prevent conflicts with your existing website design.

Key Features

• 🤖 OpenAI Integration: Built-in support for GPT models with customizable prompts
• 🎯 Custom Actions: Execute custom functions in your page based on user messages
• 🎨 Highly Customizable: Extensive theming options with light/dark mode support
• 🔧 Style Isolation: No conflicts with your existing website styles
• 📱 Responsive Design: Works perfectly on all screen sizes
• 🔄 Real-time Updates: Live typing indicators and message synchronization
• 💾 Local Storage: Optional conversation persistence
• ⚡ TypeScript Support: Full type safety and excellent developer experience

🪣 Demo Respository

For a demonstration of how MorphChat integrates into a real website when installed externally via npm, check out the morphchat-demo-page GitHub repo repository. This project shows:

• Real-world Integration: How to integrate MorphChat into an existing website
• NPM Installation: Demonstrates the library being installed and used as a dependency
• Production-like Setup: Shows a more realistic implementation scenario
• Custom Styling: Examples of how the widget adapts to different website designs

🧩 Library Usage

Installation

Install MorphChat via npm:

npm install morphchat

Basic Setup

Here's an example for a quick-start:

import React from "react";
import { useChatWidget } from "morphchat";

// Import global styles (required for proper styling)
import "morphchat/globals.scss";

function App() {
  const { component: ChatWidget } = useChatWidget({
    prompt: {
      apiKey: "your-openai-api-key",
      instructions: "You are an e-commerce AI-powered assistant. Help users the products available in the store."
      welcomeMessage: "Hello! How can I help you today?",
      model: "gpt-4o-mini",
    },
    theme: {
      primary: "#3b82f6",
      background: "#ffffff",
      text: "#1f2937",
    },
    corner: "right",
    mode: "dark",
  });

  return (
    <div>
      <h1>My Website</h1>
      { ChatWidget }
    </div>
  );
}

Advanced Configuration

const { component: ChatWidget } = useChatWidget({
// Theme configuration
theme: {
  primary: "#8b5cf6",
  background: "#ffffff",
  text: "#1f2937",
  borderRadius: "12px",
  fontFamily: "Inter, sans-serif",
},

// Widget positioning and mode
corner: "left",
mode: "auto", // Follows system preference

// Bot and user profiles
botProfile: {
  name: "AI Assistant",
  avatar: "https://example.com/bot-avatar.png",
  showAvatar: true,
},
userProfile: {
  name: "User",
  avatar: "https://example.com/user-avatar.png",
  showAvatar: true,
},

// OpenAI configuration
prompt: {
  apiKey: process.env.REACT_APP_OPENAI_API_KEY,
  welcomeMessage: "Welcome! I\"m here to help.",
  instructions: "You are a helpful assistant. Be concise and friendly.",
  model: "gpt-4o-mini",
  timeout: 30000,
  localStorage: true, // Persist conversations
},

// Custom intro
intro: {
  title: "Chat with AI",
  subtitle: "Ask me anything!",
},

// Event handlers
events: {
  onOpen: () => console.log("Chat opened"),
  onClose: () => console.log("Chat closed"),
  onSendMessage: (message) => console.log("Message sent:", message),
},

// Widget status
status: {
  isOnline: true,
  maintenanceMode: false,
  isOpen: false,
},
});

Custom Actions

Define actions that the bot can trigger based on user interactions. Actions can have typed parameters that the AI can use to execute specific functions:

const actions = [
  {
    name: "navigate",
    description: "Navigate to a specific page on the website",
    parameters: {
      page: {
        type: "string",
        description: "The page path to navigate to (e.g., \"products\", \"about\", \"contact\")",
        required: true,
      },
    },
    function: ({ page }) => {
      window.location.href = `/${page}`;
      return `Navigating to ${page} page...`;
    },
  },
  {
    name: "addToCart",
    description: "Add a product to the shopping cart",
    parameters: {
      productId: {
        type: "string",
        description: "The unique identifier of the product",
        required: true,
      },
      quantity: {
        type: "integer",
        description: "The quantity of the product to add (default: 1)",
        required: false,
      },
    },
    function: ({ productId, quantity = 1 }) => {
      // Add to cart logic here
      console.log(`Adding ${quantity} of product ${productId} to cart`);
      return `Added ${quantity} item(s) to your cart!`;
    },
  },
];

const { component: ChatWidget } = useChatWidget({
  prompt: {
    apiKey: "your-api-key",
    actions,
    // ... other config
  },
  // ...other config
});

Development Proccess

Now I'll talk a bit about how I developed MorphChat.

Technologies

• React 18+: Modern React with hooks and functional components
• TypeScript: Full type safety and excellent developer experience
• Sass: Advanced styling with CSS custom properties
• Vite: Fast development and build tooling
• OpenAI API: Integration with GPT models

Project Structure

src/
├── lib/                    # Main library (published to npm)
│   ├── components/        # React components
│   ├── hooks/            # Custom React hooks
│   ├── types/            # TypeScript type definitions
│   ├── constants/        # Constants and default values
│   └── index.ts          # Main export file
├── demo/                  # Demo application (not published)
│   ├── components/       # Demo-specific components
│   ├── context/          # React context providers
│   └── App.tsx           # Demo main component
└── main.tsx              # Demo entry point

Development Practices

• DRY Principle: Reusable components and utilities
• Separation of Concerns: Clear separation between library and demo
• Type Safety: Comprehensive TypeScript interfaces
• Code Quality: ESLint and Prettier for consistent formatting
• Modular Architecture: Well-organized component structure