JSPM – @iv-swat/chat-widget@2.0.13

Package Exports

@iv-swat/chat-widget
@iv-swat/chat-widget/dist/index.esm.js
@iv-swat/chat-widget/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@iv-swat/chat-widget) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

A modern, customizable chat widget for React applications with file upload support.

Installation

Install the package and its peer dependencies:

# Using npm
npm install @iv-swat/chat-widget lucide-react framer-motion

# Using yarn
yarn add @iv-swat/chat-widget lucide-react framer-motion

Add Tailwind CSS configuration:

Make sure you have Tailwind CSS installed and add these configurations to your tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // ... your content configuration
    './node_modules/@iv-swat/chat-widget/**/*.{js,ts,jsx,tsx}'
  ],
  theme: {
    extend: {
      colors: {
        'hola': '#0EA5E9',
        'hola-dark': '#0284C7',
      },
      animation: {
        'fadeIn': 'fadeIn 0.5s ease-in-out',
        'slideDown': 'slideDown 0.3s ease-out',
        'slideUp': 'slideUp 0.3s ease-out',
        'spin-once': 'spin 0.5s ease-in-out',
        'text-slide-up': 'text-slide-up 0.5s ease-out forwards',
        'text-slide-up-1': 'text-slide-up 0.7s ease-out forwards',
        'text-slide-up-2': 'text-slide-up 0.9s ease-out forwards',
        'typing-1': 'typing 1s steps(20, end) forwards',
        'typing-2': 'typing 1.5s steps(40, end) 1s forwards',
        'typing-3': 'typing 2s steps(60, end) 2.5s forwards',
        'cursor-blink': 'cursor-blink 0.75s step-end infinite',
      },
      keyframes: {
        fadeIn: {
          '0%': { opacity: '0' },
          '100%': { opacity: '1' },
        },
        slideDown: {
          '0%': { transform: 'translateY(-100%)', opacity: '0' },
          '100%': { transform: 'translateY(0)', opacity: '1' },
        },
        slideUp: {
          '0%': { transform: 'translateY(100%)', opacity: '0' },
          '100%': { transform: 'translateY(0)', opacity: '1' },
        },
        'text-slide-up': {
          '0%': { 
            transform: 'translateY(40px)',
            opacity: '0'
          },
          '100%': {
            transform: 'translateY(0)',
            opacity: '1'
          },
        },
        typing: {
          '0%': { 
            width: '0',
            opacity: '1',
          },
          '100%': { 
            width: '100%',
            opacity: '1',
          },
        },
        'cursor-blink': {
          '0%, 100%': { borderRightColor: 'transparent' },
          '50%': { borderRightColor: 'currentColor' },
        },
      },
    },
  },
  plugins: [],
}

Import the styles in your main CSS file:

@tailwind base;
@tailwind components;
@tailwind utilities;

/* Add these custom utilities */
@layer utilities {
  .no-scrollbar::-webkit-scrollbar {
    display: none;
  }
  
  .no-scrollbar {
    -ms-overflow-style: none;
    scrollbar-width: none;
  }
}

Features

🎨 Modern and responsive design
📁 File upload support (drag & drop or button)
⌨️ Keyboard shortcuts:
- ESC to close chat
- Ctrl + N (or Command + N on Mac) for new chat
- Enter to send message
🎯 Quick action buttons
🌈 Customizable themes
📱 Responsive layout integration
🔧 Highly configurable

Integration Methods

The Layout component provides a smooth, animated sidebar layout with your main content. This is ideal for applications that want a persistent chat interface that smoothly transitions in and out.

import { Layout } from '@iv-swat/chat-widget';

function App() {
  const [isChatExpanded, setIsChatExpanded] = useState(false);

  return (
    <Layout 
      isChatExpanded={isChatExpanded}
      chatWidth={500} // Optional: customize chat sidebar width (default: 500px)
      chatContent={
        <ChatBox 
          onClose={() => setIsChatExpanded(false)}
          title="Chat with AI"
          theme={{
            primary: '#0EA5E9',
            secondary: '#0284C7',
            textColor: '#1F2937'
          }}
          // ... other ChatBox props
        />
      }
    >
      {/* Your main content */}
      <div className="p-4">
        <h1>Your Application</h1>
        {/* ... */}
      </div>
    </Layout>
  );
}

Layout Features:

🎯 Customizable chat sidebar width (default: 500px)
🌊 Smooth spring animations using Framer Motion
📱 Consistent sidebar behavior across all screen sizes
🎨 Clean and modern design
🔄 Automatic content resizing

Layout Props

Prop	Type	Description
`children`	`ReactNode`	Your main application content
`isChatExpanded`	`boolean`	Controls whether the chat sidebar is visible
`chatContent`	`ReactNode`	The chat interface to show in the sidebar (typically `ChatBox`)
`chatWidth`	`number`	Width of the chat sidebar in pixels (default: 500)

2. Using ChatLayout (Alternative)

The ChatLayout component is the recommended way to integrate the chat widget into your application. It handles responsive behavior and layout adjustments automatically.

// pages/_app.tsx or App.tsx
import { ChatLayout } from '@iv-swat/chat-widget';

function MyApp({ Component, pageProps }) {
  // Handle chat messages with your backend
  const handleMessage = async (message: string) => {
    try {
      const response = await fetch('your-api-endpoint', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ message })
      });
      const data = await response.json();
      return data.response;
    } catch (error) {
      console.error('Error:', error);
      return "Sorry, I'm having trouble connecting to the server.";
    }
  };

  return (
    <ChatLayout
      onMessage={handleMessage}
      config={{
        theme: {
          primary: '#0EA5E9',
          secondary: '#0284C7',
          textColor: '#1F2937'
        },
        welcomeConfig: {
          title: "Hi, How can I help you?",
          description: "I'm here to assist you!"
        },
        messageUIConfig: {
          userBubbleColor: '#0EA5E9',
          botBubbleColor: '#F8F9FA'
        }
      }}
    >
      <Component {...pageProps} />
    </ChatLayout>
  );
}

export default MyApp;

The ChatLayout component provides:

Automatic responsive layout management
Smooth transitions for chat widget
Chat state management (open/close)
Proper layout on all screen sizes
Main content adjustment when chat is open
Full-screen overlay on mobile

Layout Behavior

Desktop (lg screens):
- Main content shrinks by 400px when chat is open
- Chat appears as a sidebar
- Smooth transitions
Tablet (md screens):
- Main content shrinks by 320px when chat is open
- Chat appears as a narrower sidebar
- Smooth transitions
Mobile (sm screens):
- Chat appears as a full-screen overlay
- Main content remains unchanged
- Smooth transitions

Basic Usage

import { ChatWidget, ChatBox, ChatLayout } from '@iv-swat/chat-widget';

// Basic implementation
function App() {
  return (
    <ChatWidget
      title="Chat with AI"
      onSendMessage={async (message, file) => {
        // Handle message and file here
        console.log('Message:', message);
        console.log('File:', file);
        return 'Response from AI';
      }}
    />
  );
}

Components

1. ChatWidget (Floating Button + Chat)

import { ChatWidget } from '@iv-swat/chat-widget';

function App() {
  return (
    <ChatWidget
      title="Chat with AI"
      theme={{
        primary: '#0EA5E9',
        secondary: '#0284C7',
        textColor: '#1F2937'
      }}
      welcomeMessage={{
        title: 'Welcome!',
        description: 'How can I help you today?'
      }}
      quickActions={[
        { text: 'Help', onClick: (text) => console.log(text) },
        { text: 'Features', onClick: (text) => console.log(text) }
      ]}
      messageConfig={{
        userBubbleColor: '#0EA5E9',
        botBubbleColor: '#F8F9FA'
      }}
      onSendMessage={async (message, file) => {
        // Handle message and optional file
        return 'AI response';
      }}
      onError={(error) => {
        console.error('Error:', error);
      }}
      maxFileSize={5} // Maximum file size in MB
      acceptedFileTypes={['image/*', '.pdf', '.doc', '.docx']}
    />
  );
}

2. ChatBox (Chat Interface Only)

import { ChatBox } from '@iv-swat/chat-widget';

function App() {
  return (
    <div className="h-screen">
      <ChatBox
        title="Chat with AI"
        onClose={() => console.log('Chat closed')}
        // Same props as ChatWidget
      />
    </div>
  );
}

3. ChatLayout (Responsive Layout with Chat)

import { ChatLayout } from '@iv-swat/chat-widget';

function App() {
  return (
    <ChatLayout
      config={{
        theme: {
          primary: '#0EA5E9',
          secondary: '#0284C7',
          textColor: '#1F2937'
        },
        welcomeConfig: {
          title: 'Welcome!',
          description: 'How can I help you today?'
        },
        messageUIConfig: {
          userBubbleColor: '#0EA5E9',
          botBubbleColor: '#F8F9FA'
        }
      }}
      onMessage={async (message) => {
        return 'AI response';
      }}
    >
      <main>
        {/* Your main content */}
        <h1>Your Application</h1>
      </main>
    </ChatLayout>
  );
}

Props

Common Props

Prop	Type	Description
`title`	`string`	Chat widget title
`theme`	`Theme`	Custom theme colors
`welcomeMessage`	`WelcomeConfig`	Welcome message configuration
`quickActions`	`QuickAction[]`	Quick action buttons
`messageConfig`	`MessageUIConfig`	Message UI configuration
`onSendMessage`	`(message: string, file?: File) => Promise<string>`	Handler for sending messages
`onError`	`(error: Error) => void`	Error handler
`maxFileSize`	`number`	Maximum file size in MB
`acceptedFileTypes`	`string[]`	Accepted file types

Theme Configuration

interface Theme {
  primary: string;    // Primary color
  secondary: string;  // Secondary color
  textColor: string;  // Text color
}

Welcome Message Configuration

interface WelcomeConfig {
  title: string;       // Welcome title
  description: string; // Welcome description
  icon?: ReactNode;    // Optional icon
}

Message UI Configuration

interface MessageUIConfig {
  userBubbleColor: string; // User message bubble color
  botBubbleColor: string;  // Bot message bubble color
}

File Upload

The chat widget supports file uploads with the following features:

Drag and drop files
Click to upload button
File size validation
File type validation
File preview before sending
Attach files to messages

Example file upload handling:

<ChatWidget
  maxFileSize={5} // 5MB
  acceptedFileTypes={['image/*', '.pdf', '.doc', '.docx']}
  onSendMessage={async (message, file) => {
    if (file) {
      const formData = new FormData();
      formData.append('file', file);
      formData.append('message', message);
      
      // Upload to your server
      const response = await fetch('your-api/upload', {
        method: 'POST',
        body: formData
      });
      
      return 'File uploaded successfully!';
    }
    
    // Handle text-only message
    return 'Message received!';
  }}
  onError={(error) => {
    console.error('Upload error:', error);
  }}
/>

Keyboard Shortcuts

Enter: Send message
Shift + Enter: New line in message

Styling

The chat widget uses Tailwind CSS classes by default. You can override styles by:

Using the theme prop for colors
Targeting specific classes in your CSS
Using the messageConfig prop for message bubbles

Best Practices

Error Handling: Always provide an onError handler to manage errors gracefully
File Validation: Set appropriate maxFileSize and acceptedFileTypes
Responsive Design: Use ChatLayout for better integration with your app
Message Handling: Implement proper message handling in onSendMessage
Theme Consistency: Use theme colors that match your application

License

MIT

@iv-swat/chat-widget