🚀 NUI Chatbot Package

A powerful, customizable React chatbot component library with streaming responses, floating UI, dynamic card rendering, and Tailwind/CSS theming support.

Perfect for integrating AI-powered conversations into your applications.

✨ Features

• 🎨 Customizable theming (CSS variables + Tailwind support)
• 💬 Streaming responses (typewriter effect)
• 🔌 Component registry for dynamic UI rendering
• 📱 Floating chatbot UI
• 🎯 Fully type-safe (TypeScript)

📋 Requirements

• React 18+
• React DOM 18+
• Tailwind CSS 3+

📦 Installation

npm install nui-strapi-chatbot-react
yarn add nui-strapi-chatbot-react
pnpm add nui-strapi-chatbot-react

⚙️ Additional Setup (IMPORTANT)

1️⃣ Create card-mapping.json

Inside your project's /public folder:

[
  { "id": "card1", "label": "Card 1" },
  { "id": "card2", "label": "Card 2" }
]

2️⃣ Enable CORS (Next.js)

Create middleware.ts in your project root:

import { NextResponse, NextRequest } from "next/server";

export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname === "/card-mapping.json") {
    const response = NextResponse.next();

    response.headers.set("Access-Control-Allow-Origin", "*");
    response.headers.set("Access-Control-Allow-Methods", "GET, OPTIONS");
    response.headers.set("Access-Control-Allow-Headers", "*");

    return response;
  }
}

2️⃣ Alternative: Enable CORS (Vite)

If using Vite instead of Next.js, add proxy configuration to vite.config.ts:

export default {
  server: {
    proxy: {
      "/api": {
        target: "http://localhost:1337",
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, "/api"),
      },
    },
  },
};

3️⃣ Install & Connect Strapi Backend (REQUIRED)

This component requires a Strapi backend with the FAQ chatbot plugin to function properly.

#### Install Strapi Backend Plugin

**Step 1: Create a new Strapi project**

```bash
npx create-strapi@latest my-strapi-project
cd my-strapi-project

Step 2: Install the FAQ Chatbot Plugin

yarn add nui-strapi-chatbot-plugin

Or with npm:

npm install nui-strapi-chatbot-plugin

Step 3: Start the Strapi server

npm run develop
# or
yarn develop

This will start the Strapi backend on http://localhost:1337 (default).

Step 4: Configure the Plugin

For detailed setup and configuration instructions, visit the plugin documentation: 👉 Setup Guide

Connect Strapi URL in Your Component

Pass the Strapi URL to the ChatBot component:

<ChatBot
  strapiUrl="http://localhost:1337" // Your Strapi backend URL
  cardRegistry={cardRegistry}
  title="My Chatbot"
  theme={{
    primaryColor: "#30b3eb",
    secondaryColor: "#2281f4",
    accentColor: "#38c7da",
  }}
/>

Plugin Documentation & Setup Guide

For complete setup, configuration, and troubleshooting of the Strapi FAQ Chatbot Plugin: 👉 Strapi FAQ Chatbot Plugin Repository

🚀 Quick Start

"use client";

import { ChatBot } from "nui-strapi-chatbot-react";
import "nui-strapi-chatbot-react/style.css";

const registryData = [{ id: "card1", component: DealCard }];

const customTheme = {
  primaryColor: "#1A3A72",
  secondaryColor: "#2563EB",
  containerStyle: { borderRadius: "1rem" },
  headerStyle: {
    background: "linear-gradient(135deg, #1A3A72 0%, #2563EB 100%)",
  },
  inputStyle: {
    borderRadius: "0.75rem",
  },
  userBubbleStyle: {
    background: "linear-gradient(135deg, #1D4ED8 0%, #3B82F6 100%)",
  },
  showGradient: true,
  welcomeDescription: "Hi! 👋 I'm here to help. What can I do for you?",
};

export default function ChatBotWrapper() {
  return (
    <ChatBot
      strapiUrl="https://api.example.com"
      cardRegistry={registryData}
      theme={customTheme}
      title="My Assistant"
      streamSpeed={10}
    />
  );
}

🧩 Component Registry

import DealCard from "./DealCard";
import EmployeeCard from "./EmployeeCard";
import TourCard from "./TourCard";
import GenericCard from "./GenericCard";

export const registryData = [
  { id: "card1", component: DealCard },
  { id: "card2", component: EmployeeCard },
  { id: "card3", component: TourCard },
  { id: "default", component: GenericCard },
];

🧱 Custom Card Example

interface CardProps {
  data: any;
}

export default function DealCard({ data }: CardProps) {
  return (
    <div className="bg-white rounded-lg p-4 shadow-md">
      <h3 className="font-bold">{data.title}</h3>
      <p>{data.description}</p>
      <p className="text-blue-600 font-semibold">{data.price}</p>
    </div>
  );
}

🎨 Theme Configuration

const customTheme = {
  // Primary color for accents and buttons
  primaryColor: "#1A3A72",

  // Secondary color for gradients and secondary elements
  secondaryColor: "#2563EB",

  // Container styling (border radius, padding, etc.)
  containerStyle: {
    borderRadius: "1rem",
    // Add any other CSS properties as needed
  },

  // Header styling (background, text color, etc.)
  headerStyle: {
    background: "linear-gradient(135deg, #1A3A72 0%, #2563EB 100%)",
    // Add any other CSS properties as needed
  },

  // Input field styling
  inputStyle: {
    borderRadius: "0.75rem",
    // Add any other CSS properties as needed
  },

  // User message bubble styling
  userBubbleStyle: {
    background: "linear-gradient(135deg, #1D4ED8 0%, #3B82F6 100%)",
    // Add any other CSS properties as needed
  },

  // Enable gradient effects
  showGradient: true,

  // Welcome message shown when chat loads
  welcomeDescription: "Hi! 👋 I'm your assistant. How can I help?",
};

📚 Props API

ChatBot Component Props

| Prop | Type | Required | Description | | -------------- | -------------------- | -------- | ------------------------------------------------------------- | | strapiUrl | string | ✅ | Strapi/CMS backend URL (e.g., "https://api.example.com") | | cardRegistry | CardRegistryItem[] | ✅ | Array of custom card components for rendering dynamic content | | title | string | ❌ | Display title shown in chat header | | theme | ChatTheme | ❌ | Custom theme configuration for colors and styles | | streamSpeed | number | ❌ | Streaming response speed in milliseconds (default: 10ms) |

Theme Object Properties

| Property | Type | Description | | -------------------- | ------------------ | ----------------------------------------------------- | | primaryColor | string (hex/rgb) | Primary accent color for UI elements | | secondaryColor | string (hex/rgb) | Secondary color for gradients and accents | | containerStyle | CSSProperties | Custom CSS styles for the container | | headerStyle | CSSProperties | Custom CSS styles for the header (supports gradients) | | inputStyle | CSSProperties | Custom CSS styles for the input field | | userBubbleStyle | CSSProperties | Custom CSS styles for user message bubbles | | showGradient | boolean | Enable/disable gradient effects (default: false) | | welcomeDescription | string | Welcome message displayed when chat opens |

🧾 Message Type

interface Message {
  id: number;
  role: "user" | "assistant";
  content: string;
  record?: any;
  recordType?: string;
  loading?: boolean;
}

🔌 API Format

Request:

{
  "message": "Hello"
}

Response:

{
  "answer": "Hi there!",
  "deal": null,
  "allowedFields": []
}

🎨 Styling

CSS Variables

--cb-primary: #2999d6;
--cb-secondary: #179fa3;
--cb-accent: #179fa3;

⚡ Performance Tips

• Memoize custom cards
• Lazy load heavy components
• Optimize images
• Tune streamSpeed
• Use production builds

🐛 Troubleshooting

Styles not loading

import "nui-strapi-chatbot-react/style.css";

Cards not rendering

• Check card-mapping.json
• Match registry IDs
• Verify component exports

Streaming not working

• Adjust streamSpeed
• Check API format

🌍 Browser Support

• Chrome
• Firefox
• Safari
• Edge

📄 License

ISC © 2026 Numentica UI