reactflowchat-react

Highly customizable flow-based React chat widget.

Installation

npm install react react-dom reactflowchat-react

If you want to use the engine directly outside the UI, install reactflowchat-core too.

Basic usage

import { ChatWidget } from "reactflowchat-react";
import type { Flow } from "reactflowchat-react";

const flow: Flow = {
  id: "support-chat",
  start: "welcome",
  nodes: {
    welcome: {
      type: "message",
      text: "Hello! How can I help you?",
      next: "askName",
    },
    askName: {
      type: "input",
      key: "name",
      placeholder: "Enter your name...",
      validate: { required: true, minLen: 2 },
      next: "chooseOption",
    },
    chooseOption: {
      type: "choice",
      text: "Nice to meet you, {{name}}. What do you need?",
      options: [
        { label: "Support", value: "support", next: "end" },
        { label: "Sales", value: "sales", next: "end" },
      ],
    },
    end: {
      type: "end",
      text: "Thanks. We will continue from here.",
    },
  },
};

export default function App() {
  return <ChatWidget flow={flow} />;
}

API

ChatWidget

import { ChatWidget } from "reactflowchat-react";

Props

type ChatWidgetProps = {
  flow: Flow;
  persistence?: "localStorage" | "sessionStorage" | "none";
  storageKey?: string;
  bot?: BotConfig;
  user?: UserConfig;
  icons?: IconsConfig;
  theme?: Theme;
  position?: Position;
  labels?: Labels;
  features?: Features;
  layout?: Layout;
  onComplete?: (ctx: Record<string, any>) => void;
};

Flow shape

type Flow = {
  id: string;
  start: string;
  nodes: Record<string, Node>;
};

type Node = MessageNode | InputNode | ChoiceNode | EndNode;

type MessageNode = {
  type: "message";
  text: string;
  next?: string;
};

type InputNode = {
  type: "input";
  key: string;
  placeholder?: string;
  validate?: {
    required?: boolean;
    minLen?: number;
    pattern?: string;
  };
  next?: string;
};

type ChoiceNode = {
  type: "choice";
  text: string;
  options: Array<{
    label: string;
    value: string;
    next: string;
  }>;
  next?: string;
};

type EndNode = {
  type: "end";
  text?: string;
};

Props examples

<ChatWidget
  flow={flow}
  persistence="localStorage"
  storageKey="my-chat"
  bot={{
    name: "Support Bot",
    avatarUrl: "/bot.png",
    typingMs: 800,
  }}
  user={{
    avatarMode: "randomAnimal",
    avatarUrls: ["/avatars/cat.png", "/avatars/dog.png", "/avatars/fox.png"],
  }}
  position={{ right: 24, bottom: 24 }}
  features={{
    defaultOpen: false,
    showReset: true,
    showHeader: true,
    showFooter: true,
    showBotAvatar: true,
    showUserAvatar: true,
    closeOnEsc: true,
    closeOnOutsideClick: true,
  }}
  labels={{
    openChat: "Open chat",
    closeChat: "Close chat",
    reset: "Reset",
    typing: "Typing...",
    online: "Online",
    finished: "Conversation finished.",
    pickOption: "Choose an option...",
    inputPlaceholderFallback: "Type here...",
    botTypingAria: "Bot typing",
    dialogAriaLabel: "Chat widget",
  }}
  layout={{
    panelWidth: 400,
    panelHeight: 560,
    launcherSize: 62,
    launcherIconSize: 26,
    headerAvatarSize: 38,
    miniAvatarSize: 26,
    bubbleMaxWidthPct: 76,
    bodyPadding: 12,
  }}
  theme={{
    primary: "#ed3a93",
    headerBg: "linear-gradient(135deg, #111827, #312e81)",
    headerText: "#ffffff",
    panelBg: "#ffffff",
    bodyBg: "#f6f7fb",
    botBubbleBg: "#ffffff",
    botBubbleText: "#0f172a",
    userBubbleBg: "#ed3a93",
    userBubbleText: "#ffffff",
    borderColor: "rgba(2,6,23,.10)",
    shadow: "0 24px 60px rgba(2,6,23,.20)",
    radius: 22,
    inputBg: "#ffffff",
    inputText: "#0f172a",
    inputPlaceholder: "rgba(15,23,42,.45)",
    inputBorder: "rgba(2,6,23,.14)",
    inputFocusBorder: "rgba(237,58,147,.55)",
    focusRing: "#ed3a93",
    focusRingAlpha: 0.22,
    chipBg: "rgba(255,255,255,.92)",
    chipText: "#0f172a",
    chipBorder: "rgba(2,6,23,.14)",
    botAvatarBg: "rgba(255,255,255,.14)",
    miniAvatarBg: "rgba(255,255,255,.92)",
    miniAvatarBorder: "rgba(2,6,23,.10)",
    launcherBorder: "rgba(255,255,255,.25)",
    launcherShadow: "0 18px 35px rgba(2,6,23,.22)",
    launcherOverlay: "radial-gradient(120% 120% at 20% 10%, rgba(255,255,255,.25), transparent 60%)",
    launcherHoverBrightness: 1.02,
    sendBg: "#111827",
    sendText: "#ffffff",
    sendDisabledOpacity: 0.45,
    typingDotsColor: "rgba(17,24,39,.55)",
  }}
  onComplete={(ctx) => {
    console.log("Flow completed", ctx);
  }}
/>

Exports

The package exports:

• ChatWidget
• Flow
• Node
• ChatState
• ChatMessage
• Persistence
• ChatWidgetProps
• BotConfig
• UserConfig
• IconsConfig
• IconSource
• Theme
• Layout
• Labels
• Features
• Position

Persistence

Supported values:

• localStorage
• sessionStorage
• none

License

MIT