@vanillaodyssey/knowlet-react

React components and hooks for integrating Knowlet AI chat functionality into your applications.

Installation

npm install @vanillaodyssey/knowlet-react
# or
yarn add @vanillaodyssey/knowlet-react

Quick Start

Basic Chat Component

import React from 'react';
import { KnowletChat } from '@vanillaodyssey/knowlet-react';

function App() {
  return (
    <div style={{ height: '500px', width: '400px' }}>
      <KnowletChat 
        apiKey="your-knowlet-api-key"
        config={{
          title: 'My AI Assistant',
          primaryColor: '#3b82f6',
          welcomeMessage: 'Hello! How can I help you today?'
        }}
      />
    </div>
  );
}

export default App;

Using the Hook

import React, { useState } from 'react';
import { useKnowletChat } from '@vanillaodyssey/knowlet-react';

function CustomChat() {
  const [input, setInput] = useState('');
  
  const { messages, isLoading, sendMessage, clearMessages } = useKnowletChat({
    apiKey: 'your-knowlet-api-key',
    apiUrl: 'https://knowlet-ai.bizblocks.org', // optional
  });

  const handleSend = async () => {
    if (input.trim()) {
      await sendMessage(input);
      setInput('');
    }
  };

  return (
    <div>
      <div>
        {messages.map((message) => (
          <div key={message.id}>
            <strong>{message.isUser ? 'You' : 'AI'}:</strong> {message.text}
          </div>
        ))}
      </div>
      
      <input 
        value={input} 
        onChange={(e) => setInput(e.target.value)}
        onKeyPress={(e) => e.key === 'Enter' && handleSend()}
      />
      <button onClick={handleSend} disabled={isLoading}>
        Send
      </button>
      <button onClick={clearMessages}>Clear</button>
    </div>
  );
}

API Reference

KnowletChat Component

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | apiKey | string | ✅ | Your Knowlet API key | | config | Partial<KnowletConfig> | ❌ | Configuration options | | className | string | ❌ | Additional CSS classes | | style | React.CSSProperties | ❌ | Inline styles | | maxHeight | string \| number | ❌ | Maximum height constraint for the chat container |

KnowletConfig Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiUrl | string | 'https://knowlet-ai.bizblocks.org' | API endpoint URL | | theme | 'modern' \| 'minimal' \| 'dark' | 'modern' | Chat theme (use 'dark' for dark mode) | | primaryColor | string | '#3b82f6' | Primary color for UI elements | | title | string | 'Chat' | Chat header title | | logoUrl | string | undefined | Logo URL for header | | welcomeMessage | string | 'Hello! How can I help you today?' | Initial welcome message | | defaultPrompts | string[] | [] | Suggested prompts to display | | processStreamText | boolean | false | Enable advanced text processing | | layout | 'simple' \| 'advanced' | 'simple' | Layout mode: simple (embedded) or advanced (full-screen with sidebar) |

useKnowletChat Hook

Parameters

interface UseKnowletChatOptions {
  apiKey: string;
  apiUrl?: string;
  sessionId?: string;
  processStreamText?: boolean;
}

Returns

interface UseKnowletChatReturn {
  messages: Message[];
  isLoading: boolean;
  sendMessage: (message: string) => Promise<void>;
  clearMessages: () => void;
  sessionId: string;
}

Message Type

interface Message {
  id: string;
  text: string;
  isUser: boolean;
  timestamp: Date;
  isStreaming?: boolean;
  actions?: WebAction[];
  totalActions?: number;
}

Styling

The package includes Tailwind CSS classes. Make sure you have Tailwind CSS configured in your project, or the styles may not appear correctly.

Custom Styling

You can override styles using CSS classes or inline styles:

<KnowletChat 
  apiKey="your-api-key"
  className="my-custom-chat"
  style={{ 
    height: '600px', 
    borderRadius: '20px',
    boxShadow: '0 10px 30px rgba(0,0,0,0.1)'
  }}
  config={{
    primaryColor: '#ff6b6b'
  }}
/>

Features

• 🚀 Real-time streaming - Messages stream in real-time as the AI responds
• 🌙 Dark mode support - Beautiful dark theme with automatic color inversion
• 🎨 Customizable styling - Easy theming with Tailwind CSS and custom colors
• 📱 Responsive design - Works on all screen sizes
• ⚡ TypeScript support - Full type safety and IntelliSense
• 🔌 Flexible integration - Use the component or hook for custom implementations
• 🛡️ Error handling - Robust error handling and recovery
• 💬 Markdown support - Rich text formatting in chat messages
• 🔄 Scrollable prompts - Suggested prompts display in a single scrollable row with navigation arrows

Suggested Prompts

The defaultPrompts configuration now displays prompts in a single horizontal scrollable row with intuitive navigation:

<KnowletChat 
  apiKey="your-api-key"
  config={{
    defaultPrompts: [
      'What can you help me with?',
      'Tell me about your features',
      'How do I get started?',
      'Show me pricing options',
      'What are the benefits?',
      'How does integration work?',
      'What support is available?',
      // Add as many as you want!
    ]
  }}
/>

Features:

• Single row layout - No more wrapping to multiple lines
• Hidden scrollbar - Clean appearance without visible scrollbars
• Navigation arrows - Left/right arrows appear automatically when needed
• Smooth scrolling - Elegant scrolling behavior with proper momentum
• Responsive - Works perfectly on all screen sizes
• Auto-hide arrows - Arrows only show when there's content to scroll to

Perfect for providing many suggested prompts without cluttering the interface!

Advanced Layout Mode

The package now supports a new advanced layout mode with a full-screen interface and left sidebar navigation:

Enabling Advanced Layout

<div style={{ height: '100vh', width: '100vw' }}>
  <KnowletChat 
    apiKey="your-api-key"
    config={{
      layout: 'advanced',          // Enable advanced layout
      title: 'AI Assistant',
      primaryColor: '#3b82f6',
      welcomeMessage: 'Welcome! Use the sidebar to navigate.',
      defaultPrompts: [
        'Show me my files',
        'Start new conversation',
        'Help with navigation',
        'What are the features?'
      ]
    }}
  />
</div>

Advanced Layout Features

• 🗂️ File Management - Browse and download files from your tenant directory
• 💬 Chat Navigation - Sidebar for managing multiple conversations (coming soon)
• 📱 Full-Screen Interface - Optimized for full-width/height applications
• 🎨 Consistent Theming - Respects all existing theme and color configurations
• 📁 File Browser - Navigate folders, view file metadata, and download files
• 🆕 New Chat Button - Easy conversation management

Layout Comparison

| Feature | Simple Layout | Advanced Layout | |---------|---------------|-----------------| | Container | Flexible sizing | Full screen (100vw × 100vh) | | Navigation | Basic chat only | Sidebar with chats & files | | File Access | Not available | Full file browser | | Use Cases | Embedded widgets, popups | Admin panels, full apps | | Mobile | Optimized | Desktop-first (mobile coming soon) |

File Management

The advanced layout includes a built-in file browser that:

• Lists files from your tenant's directory via /admin/files/list
• Supports folder navigation
• Shows file metadata (size, date modified)
• Enables file downloads with a simple click
• Respects API key permissions and tenant isolation

When to Use Advanced Layout

Use Simple Layout (default) for:

• Embedded chat widgets
• Modal dialogs
• Customer support popups
• Mobile applications
• Constrained spaces

Use Advanced Layout for:

• Full-screen applications
• Admin dashboards
• Document management systems
• Internal tools
• Desktop applications

Height Constraints and Scrolling

The KnowletChat component now properly handles height constraints and scrolling behavior:

Setting Height Limits

Method 1: Using maxHeight prop (Recommended)

<KnowletChat 
  apiKey="your-api-key"
  maxHeight="400px"  // Direct height control
  config={{
    title: 'Height Constrained Chat'
  }}
/>

Method 2: CSS max-height classes

<div className="max-h-96"> {/* Tailwind: max-height: 24rem */}
  <KnowletChat 
    apiKey="your-api-key"
    config={{ title: 'CSS Constrained Chat' }}
  />
</div>

Method 3: Container with fixed height

<div style={{ height: '400px' }}>
  <KnowletChat 
    apiKey="your-api-key"
    config={{ title: 'Container Constrained Chat' }}
  />
</div>

Scrolling Behavior

When height constraints are applied:

• ✅ Messages area: Scrolls independently when content overflows
• ✅ Header: Remains fixed at the top
• ✅ Input area: Remains fixed at the bottom
• ✅ Auto-scroll: Automatically scrolls to show new messages
• ✅ Smooth scrolling: Enhanced scroll behavior with proper momentum

Best Practices

1. Use maxHeight prop for explicit height control
2. Minimum height: Component enforces 300px minimum for usability
3. Responsive: Height constraints work across all screen sizes
4. Flex layout: Uses proper CSS flexbox for reliable behavior

Common Issues Fixed

• ❌ Before: max-height classes didn't limit component height
• ✅ After: Proper height constraint handling
• ❌ Before: Messages overflowed container bounds
• ✅ After: Messages scroll within defined height
• ❌ Before: Input area could be cut off
• ✅ After: Input area always visible at bottom

Dark Mode

Enable dark mode by setting theme: 'dark' in your config:

<KnowletChat 
  apiKey="your-api-key"
  config={{
    theme: 'dark', // Enables dark mode
    primaryColor: '#3b82f6',
    title: 'Dark Mode Chat',
    welcomeMessage: 'Welcome to dark mode!'
  }}
/>

In dark mode:

• Background uses dark gray colors
• Text becomes white for better contrast
• Primary color becomes white in headers
• Icons and buttons are automatically inverted
• All interactive elements are optimized for dark theme

See DARK_MODE_GUIDE.md for detailed documentation.

Requirements

• React 16.8+
• TypeScript (recommended)
• Tailwind CSS (for styling)

License

MIT