💬 IGNIS Flow Playground

A production-ready React Playground package the embedded/widget version of the IgnisFlow playground. Built with TypeScript, Tailwind CSS, and React for seamless integration into modern applications.

Perfect for: AI-powered chat interfaces, embedded assistants, bubble chat widgets, LangFlow-powered flows.

📋 Table of Contents

• Key Features
• Installation
• Package Exports
• Configuration
• React Integration Guide
• Next.js Integration
• Standalone / IIFE Bundle
• Styling & Customization
• Troubleshooting

🚀 Key Features

• Production-Ready - Battle-tested components with comprehensive type safety
• Two Display Modes - embedded for inline UI integration, bubble for a floating chat button
• LangFlow Integration - Connects directly to LangFlow flows via flowId and apiBaseUrl
• Streaming Support - Real-time streaming responses via server-sent events
• Flexible Authentication - Support for Bearer tokens and custom request headers
• Responsive Design - Mobile-friendly adaptive chat UI that works on all screen sizes
• TypeScript Support - Full type definitions for an enhanced developer experience
• Event Callbacks - onMessage and onError callbacks for advanced integration
• Redux State Management - Internal state management with Redux Toolkit
• React Router - Internal router context — no setup required in the host app

📦 Installation

From npm

Install directly from the npm registry:

npm install @tenarai-ignis/ignisflowplayground

Peer Dependencies

This package requires React 16.8+ and React DOM 16.8+:

npm install react react-dom

Quick Start

import { ReactChatbot } from '@tenarai-ignis/ignisflowplayground/react-chatbot';
import '@tenarai-ignis/ignisflowplayground/styles';

function App() {
  return (
    <ReactChatbot
      config={{
        mode: 'embedded',
        apiBaseUrl: 'https://your-langflow-api.com',
        flowId: 'your-flow-id',
        token: 'your-auth-token',
        eventDelivery: 'streaming',
      }}
    />
  );
}

📤 Package Exports

| Import Path | Description | |---|---| | @tenarai-ignis/ignisflowplayground | Main bundle — all exports | | @tenarai-ignis/ignisflowplayground/react-chatbot | React chatbot component only (smaller bundle) | | @tenarai-ignis/ignisflowplayground/styles | Required CSS styles |

Named Exports

// Main bundle
import {
  ReactChatbot,
  type ChatbotConfig,
  type ChatbotProps,
  type ChatbotMessage,
} from '@tenarai-ignis/ignisflowplayground';

// Chatbot only (smaller bundle — recommended)
import { ReactChatbot, type ChatbotConfig } from '@tenarai-ignis/ignisflowplayground/react-chatbot';

// Styles (required — import once at app root)
import '@tenarai-ignis/ignisflowplayground/styles';

| Export | Type | Description | |---|---|---| | ReactChatbot | React Component | Main chatbot component for React apps | | ChatbotConfig | TypeScript Interface | Full config type definition | | ChatbotProps | TypeScript Interface | Props type for the chatbot component | | ChatbotMessage | TypeScript Interface | Chat message structure type |

⚙️ Configuration

ChatbotConfig Reference

interface ChatbotConfig {
  // LangFlow connection
  apiBaseUrl?: string;          // Base URL of your LangFlow instance
  flowId?: string;              // LangFlow flow ID to run
  startComponentId?: string;    // Optional: starting component in the flow

  // Authentication
  token?: string;               // Bearer token sent in Authorization header
  headers?: Record<string, string>; // Additional custom headers

  // API options
  chatApiUrl?: string;          // Full chat URL (overrides apiBaseUrl + chatEndpoint)
  chatEndpoint?: string;        // Chat endpoint path (default: /api/v1/run)
  eventDelivery?: 'streaming' | 'polling'; // Response delivery mode (default: 'streaming')

  // Display mode
  mode?: 'embedded' | 'bubble'; // embedded = inline, bubble = floating button (default: 'embedded')

  // UI customization
  title?: string;               // Chat window title
  placeholder?: string;         // Input placeholder text
  welcomeMessage?: string;      // Initial greeting message
  bubbleLabel?: string;         // Floating button label (bubble mode only)
  autoOpen?: boolean;           // Auto-open the chat on load (bubble mode)
  position?: 'bottom-right' | 'bottom-left'; // Bubble position (default: 'bottom-right')
  width?: number;               // Chat window width in px (bubble mode, default: 380)
  height?: number;              // Chat window height in px (bubble mode, default: 560)
  zIndex?: number;              // CSS z-index (bubble mode, default: 9999)
  theme?: 'light' | 'dark';    // Color theme

  // Optional metadata passed to the backend
  metadata?: Record<string, any>;
}

Configuration Examples

Embedded Mode (inline chat panel):

const config: ChatbotConfig = {
  mode: 'embedded',
  apiBaseUrl: 'https://ignisflow.yourcompany.com',
  flowId: 'abc123-def456',
  token: sessionStorage.getItem('token') ?? '',
  eventDelivery: 'streaming',
  title: 'AI Assistant',
  welcomeMessage: 'Hello! How can I help you today?',
};

Bubble Mode (floating button):

const config: ChatbotConfig = {
  mode: 'bubble',
  apiBaseUrl: 'https://ignisflow.yourcompany.com',
  flowId: 'abc123-def456',
  token: sessionStorage.getItem('token') ?? '',
  bubbleLabel: 'Chat with AI',
  position: 'bottom-right',
  width: 400,
  height: 600,
  autoOpen: false,
};

With custom headers (e.g. Azure AD):

const config: ChatbotConfig = {
  mode: 'embedded',
  apiBaseUrl: 'https://ignisflow.yourcompany.com',
  flowId: 'abc123-def456',
  token: getAuthToken(),
  headers: {
    'x-auth-type': 'azure',
    'x-api-key': import.meta.env.VITE_API_KEY,
    'x-tenant-id': getCurrentTenantId(),
  },
  eventDelivery: 'streaming',
};

? React Integration Guide

Basic Usage

import React from 'react';
import { ReactChatbot, type ChatbotConfig } from '@tenarai-ignis/ignisflowplayground/react-chatbot';
import '@tenarai-ignis/ignisflowplayground/styles';

const ChatbotPage: React.FC = () => {
  const config: ChatbotConfig = {
    mode: 'embedded',
    apiBaseUrl: 'https://ignisflow.yourcompany.com',
    flowId: 'your-flow-id',
    token: sessionStorage.getItem('token') ?? '',
    eventDelivery: 'streaming',
  };

  return (
    <div style={{ height: '100vh' }}>
      <ReactChatbot config={config} />
    </div>
  );
};

export default ChatbotPage;

Bubble Mode

import React from 'react';
import { ReactChatbot, type ChatbotConfig } from '@tenarai-ignis/ignisflowplayground/react-chatbot';
import '@tenarai-ignis/ignisflowplayground/styles';

const App: React.FC = () => {
  const config: ChatbotConfig = {
    mode: 'bubble',
    apiBaseUrl: 'https://ignisflow.yourcompany.com',
    flowId: 'your-flow-id',
    token: sessionStorage.getItem('token') ?? '',
    bubbleLabel: 'Ask AI',
    position: 'bottom-right',
    autoOpen: false,
  };

  return (
    <div>
      {/* Your app content */}
      <h1>My Application</h1>
      {/* Chatbot renders as a floating bubble — no layout impact */}
      <ReactChatbot config={config} />
    </div>
  );
};

With Event Callbacks

import React from 'react';
import { ReactChatbot, type ChatbotConfig, type ChatbotMessage } from '@tenarai-ignis/ignisflowplayground/react-chatbot';
import '@tenarai-ignis/ignisflowplayground/styles';

const ChatbotPage: React.FC = () => {
  const config: ChatbotConfig = {
    mode: 'embedded',
    apiBaseUrl: 'https://ignisflow.yourcompany.com',
    flowId: 'your-flow-id',
    token: getAuthToken(),
  };

  const handleMessage = (message: ChatbotMessage) => {
    console.log('New message:', message);
    // Track analytics, trigger side effects, etc.
  };

  const handleError = (error: Error) => {
    console.error('Chatbot error:', error);
    showErrorNotification(error.message);
  };

  return (
    <ReactChatbot
      config={config}
      onMessage={handleMessage}
      onError={handleError}
    />
  );
};

🔷 Next.js Integration

App Router (Next.js 13+)

The chatbot is a client-side component. Add 'use client' at the top:

// app/chat/page.tsx
'use client';

import { ReactChatbot, type ChatbotConfig } from '@tenarai-ignis/ignisflowplayground/react-chatbot';
import '@tenarai-ignis/ignisflowplayground/styles';

export default function ChatPage() {
  const config: ChatbotConfig = {
    mode: 'embedded',
    apiBaseUrl: process.env.NEXT_PUBLIC_LANGFLOW_API!,
    flowId: process.env.NEXT_PUBLIC_FLOW_ID!,
    token: process.env.NEXT_PUBLIC_AUTH_TOKEN!,
    eventDelivery: 'streaming',
  };

  return (
    <div className="h-screen">
      <ReactChatbot config={config} />
    </div>
  );
}

Pages Router (Next.js 12 and below)

Use dynamic import with ssr: false:

// pages/chat.tsx
import dynamic from 'next/dynamic';
import type { ChatbotConfig } from '@tenarai-ignis/ignisflowplayground/react-chatbot';

const ReactChatbot = dynamic(
  () => import('@tenarai-ignis/ignisflowplayground/react-chatbot').then(mod => mod.ReactChatbot),
  { ssr: false }
);

export default function ChatPage() {
  const config: ChatbotConfig = {
    mode: 'embedded',
    apiBaseUrl: process.env.NEXT_PUBLIC_LANGFLOW_API!,
    flowId: process.env.NEXT_PUBLIC_FLOW_ID!,
    token: process.env.NEXT_PUBLIC_AUTH_TOKEN!,
  };

  return (
    <div style={{ height: '100vh' }}>
      <ReactChatbot config={config} />
    </div>
  );
}

Environment Variables (.env.local)

NEXT_PUBLIC_LANGFLOW_API=https://ignisflow.yourcompany.com
NEXT_PUBLIC_FLOW_ID=your-langflow-flow-id
NEXT_PUBLIC_AUTH_TOKEN=your-jwt-token

📦 Standalone / IIFE Bundle

For non-React apps or plain HTML pages, use the standalone IIFE build.

Build

npm run build:chatbot-bundle

Usage in HTML

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="./dist/chatbot-standalone/ignis-chatbot-styles.css" />
</head>
<body>
  <div id="chat-root"></div>

  <script src="./dist/chatbot-standalone/ignis-chatbot.iife.js"></script>
  <script>
    // Embedded mode
    window.IgnisChatbot.init('#chat-root', {
      mode: 'embedded',
      apiBaseUrl: 'https://ignisflow.yourcompany.com',
      flowId: 'your-flow-id',
      token: 'your-auth-token',
      eventDelivery: 'streaming',
    });
  </script>
</body>
</html>

Bubble mode:

window.IgnisChatbot.init(document.body, {
  mode: 'bubble',
  apiBaseUrl: 'https://ignisflow.yourcompany.com',
  flowId: 'your-flow-id',
  token: 'your-auth-token',
  bubbleLabel: 'Chat with AI',
  position: 'bottom-right',
});

🎨 Styling & Customization

Import Styles

Always import styles once at your app root:

// In main.tsx / index.tsx / _app.tsx
import '@tenarai-ignis/ignisflowplayground/styles';

Tailwind CSS Content Path

If your project uses Tailwind CSS, add the package to your content paths:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@tenarai-ignis/ignisflowplayground/dist/**/*.{js,mjs}',
  ],
};

Custom Container Dimensions

{/* Fixed height container for embedded mode */}
<div style={{ width: '100%', height: '700px', borderRadius: '12px', overflow: 'hidden' }}>
  <ReactChatbot config={config} />
</div>

🔍 Troubleshooting

Common Issues

useNavigate / Router Error:

You cannot render a <Router> inside another <Router>

The module bundles its own router context via MemoryRouter. Do not wrap it in another <BrowserRouter> or <MemoryRouter> in the host app.

Chat Not Sending Messages:

• Verify apiBaseUrl is reachable from the browser
• Ensure flowId is a valid LangFlow flow ID
• Check that the token is valid and not expired
• Open browser DevTools → Network tab to inspect the request/response

401 Unauthorized:

• Verify the token value is correct and not empty
• Check if the token has expired
• Ensure headers includes any required auth headers (e.g. x-auth-type)

Styling Not Applied:

• Ensure @tenarai-ignis/ignisflowplayground/styles is imported at the app root
• Check for CSS conflicts with other UI libraries

Bubble Not Visible:

• Confirm mode: 'bubble' is set in config
• Check no parent element has overflow: hidden clipping the fixed-position bubble
• Increase zIndex (default: 9999) if another element overlays the button

Getting Help

1. Check the browser console for error messages
2. Verify the LangFlow API is accessible from the browser
3. Ensure all required config properties (apiBaseUrl, flowId, token) are set
4. Visit tenarai.com for support

📄 License

MIT License - Use freely in commercial and personal projects.

See LICENSE file for details.

Package Version: 0.0.1
Last Updated: July 2026
Published: @tenarai-ignis/ignisflowplayground on npm
Maintained by: Tenarai Ignis Team
Get Started Today: npm install @tenarai-ignis/ignisflowplayground