Features

• JSON-driven flows — Build conversational UIs with step-based JSON configuration
• Keyword matching — Route user text to responses or flow steps via pattern matching
• Greeting detection — Auto-respond to common greetings (hi, hello, hey, etc.)
• Fallback responses — Catch-all reply when no keyword or flow matches
• Input validation — Validate free-text input inside flow steps with transforms
• Async actions — Run API calls on step entry with real-time loading/progress/error states
• Custom step components — Render your own React widgets inside flow steps
• Dynamic routing — Route to different steps based on API results, status codes, or custom logic
• Plugin architecture — 30 built-in plugins: analytics, AI, webhooks, persistence, i18n, CRM, rate limiting, live agent, and more
• Slash commands — /help, /back, /cancel, /restart built-in
• customizeChat slot map — All UI customization in one prop: component overrides (bubble, quick replies, typing indicator, header, input, launcher, branding, welcome/login screen) + config (header, branding, welcome screen content)
• Custom header/input — Swap the header or input with your own React components
• Forms — Text, select, radio, checkbox, file upload, with validation
• Custom form fields — Replace any form field type with your own React component
• Theming — Light/dark mode, CSS variables, glassmorphism design
• File uploads — Drag & drop, preview, size/count limits
• Emoji picker — Built-in emoji selector
• Welcome & login screens — Optional onboarding flow
• Branding — Customizable footer and header
• Typing delay — Realistic typing pause before bot replies
• onUnhandledMessage — Callback when nothing handles user text

Installation

npm install @enjoys/react-chatbot-plugin
# or
yarn add @enjoys/react-chatbot-plugin
# or
pnpm add @enjoys/react-chatbot-plugin
# or
bun add @enjoys/react-chatbot-plugin

Peer dependencies: react >= 18.0.0, react-dom >= 18.0.0

Quick Start

import { ChatBot } from '@enjoys/react-chatbot-plugin';
import type { FlowConfig } from '@enjoys/react-chatbot-plugin';

const flow: FlowConfig = {
  startStep: 'greeting',
  steps: [
    {
      id: 'greeting',
      message: 'Hi! How can I help you?',
      quickReplies: [
        { label: 'Sales', value: 'sales', next: 'sales' },
        { label: 'Support', value: 'support', next: 'support' },
      ],
    },
    { id: 'sales', message: 'Our plans start at $29/month.' },
    { id: 'support', message: 'Please describe your issue and we will get back to you.' },
  ],
};

function App() {
  return (
    <ChatBot
      flow={flow}
      customizeChat={{
        header: { config: { title: 'Acme Support', subtitle: 'Online', showRestart: true } },
      }}
    />
  );
}

Documentation

Full documentation is available in the docs/ folder:

| # | Guide | Description | |---|-------|-------------| | 1 | Getting Started | Installation, quick start, minimal example | | 2 | Basic Flows | Steps, messages, quick replies, delays | | 3 | Forms & Validation | All 15 field types, validation rules, login forms | | 4 | Conditional Branching | If/else routing based on collected data | | 5 | Async Actions | API calls, progress messages, error handling | | 6 | Custom Components | React widgets inside flow steps | | 7 | Dynamic Routing | Route based on API response status | | 8 | Theming & Styling | Colors, CSS variables, dark mode | | 9 | Plugins | 30 built-in & custom plugins | | 10 | Slash Commands | /help, /back, /restart, /cancel | | 11 | File Upload | Drag & drop, restrictions, previews | | 12 | Custom Header & Input | Replace header/input with React components | | 13 | Advanced Patterns | E-commerce bot, onboarding wizard, full examples | | 14 | Keywords & Fallback | Keyword routes, greeting detection, fallback, typing delay | | 15 | API Reference | All types, props, and exports |

Props

| Prop | Type | Description | |------|------|-------------| | flow | FlowConfig | JSON conversation flow | | theme | ChatTheme | Colors, fonts, border radius, light/dark mode | | style | ChatStyle | CSS overrides for launcher, window, header, etc. | | loginForm | FormConfig | Pre-chat login/identification form | | callbacks | ChatCallbacks | Event handlers (onOpen, onClose, onMessageSend, etc.) | | plugins | ChatPlugin[] | Array of plugins | | initialMessages | ChatMessage[] | Pre-populated messages | | inputPlaceholder | string | Input placeholder text | | position | 'bottom-right' \| 'bottom-left' | Widget position | | enableEmoji | boolean | Show emoji picker | | fileUpload | FileUploadConfig | File upload settings | | components | Record<string, ComponentType<StepComponentProps>> | Custom React components for flow steps | | actionHandlers | Record<string, (data, ctx) => Promise<FlowActionResult>> | Async action handlers for flow steps | | defaultOpen | boolean | Start with chat open | | showLauncher | boolean | Show/hide launcher button | | launcherIcon | ReactNode | Custom launcher icon | | closeIcon | ReactNode | Custom close icon | | zIndex | number | CSS z-index | | renderFormField | FormFieldRenderMap | Custom renderers for form field types | | customizeChat | ChatCustomizeChat | All UI customization — slot configs + component overrides (see below) | | className | string | Root element class name |

customizeChat Slots

Each key is a partial of its slot props — provide config, content, or a custom component. Only provided keys are used; missing keys use defaults. Forms (DynamicForm / renderFormField) are never affected.

| Key | Slot Props | Configurable Fields | |-----|-----------|---------------------| | header | HeaderSlotProps | config: HeaderConfig, component | | input | InputSlotProps | component | | branding | BrandingSlotProps | config: BrandingConfig, component | | welcomeScreen | WelcomeScreenSlotProps | content: ReactNode, component | | loginScreen | LoginScreenSlotProps | config: FormConfig, component | | launcher | LauncherSlotProps | component | | messageBubble | MessageBubbleSlotProps | component: ComponentType | | quickReplies | QuickRepliesSlotProps | component: ComponentType | | typingIndicator | TypingIndicatorSlotProps | component: ComponentType |

<ChatBot
  flow={flow}
  customizeChat={{
    header: {
      config: { title: 'Acme Support', subtitle: 'Online', showRestart: true },
    },
    branding: {
      config: { poweredBy: 'Acme Inc', showBranding: true },
    },
    messageBubble: { component: MyCustomBubble },
    quickReplies: { component: MyCustomQuickReplies },
  }}
/>

Exported Components

All internal components are exported for advanced use cases:

UI: ChatBot, ChatHeader, ChatInput, ChatWindow, Launcher, MessageBubble, MessageList, QuickReplies, TypingIndicator, WelcomeScreen, LoginScreen, Branding, EmojiPicker, FileUploadButton, FilePreviewList, DynamicForm

Forms: TextField, SelectField, RadioField, CheckboxField, FileUploadField

Icons: SendIcon, ChatBubbleIcon, CloseIcon, MinimizeIcon, EmojiIcon, AttachmentIcon, FileIcon, ImageIcon, RemoveIcon, RestartIcon

Engine & Core: FlowEngine, PluginManager, useChat, ChatContext, useChatContext

Theme utilities: resolveTheme, buildStyles, buildCSSVariables

Built-in plugins: analyticsPlugin, webhookPlugin, persistencePlugin, loggerPlugin, crmPlugin, emailPlugin, syncPlugin, aiPlugin, intentPlugin, typingPlugin, autoReplyPlugin, validationPlugin, uploadPlugin, authPlugin, rateLimitPlugin, pushPlugin, soundPlugin, agentPlugin, transferPlugin, themePlugin, componentPlugin, leadPlugin, campaignPlugin, schedulerPlugin, reminderPlugin, i18nPlugin, debugPlugin, devtoolsPlugin, mediaPlugin, markdownPlugin

Development

# Install dependencies
bun install

# Run demo (17 interactive demos)
bun run dev

# Build library
bun run build

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT © Enjoys