# react-simple-chatbot: building a step-driven conversational UI in React

> react-simple-chatbot is a MIT-licensed TypeScript library for React 18 and 19 that renders a chatbot UI driven by a static steps array. It requires styled-components as a peer dependency and ships with CSS class names and inline style props for customisation.

**LucasBassetti/react-simple-chatbot** — :speech_balloon: Easy way to create conversation chats

- Repository: https://github.com/LucasBassetti/react-simple-chatbot
- Website: https://lucasbassetti.github.io/react-simple-chatbot/.
- Stars: 1,754 · Forks: 595
- Language: TypeScript
- License: MIT
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/lucasbassetti-react-simple-chatbot

## Steps as the unit of conversation: id, message, trigger and end

Each turn in the conversation is a step object with 4 fields. An id identifies the step, a message holds the text to display, a trigger names the id of the next step, and setting end to true closes the conversation. That chain of trigger values is the entire flow control model: there is no branching syntax, no conditionals and no loop construct in the base step definition.

The typed Step import gives TypeScript consumers compile-time guarantees on that structure. Custom component steps receive 4 props: step, steps, previousStep and triggerNextStep, all typed as CustomComponentProps. That makes a custom component aware of the full step list and able to call triggerNextStep to advance the flow programmatically rather than waiting for a message to finish.

Because the trigger field holds a string id, the step order in the array does not have to match the conversation order. A step at index 0 can point to a step at index 5 and skip index 1 through 4. How this interacts with the cache feature when steps are reordered after first render is not documented.

## styled-components is a required peer dependency, not an optional UI layer

Installing the library requires two packages: react-simple-chatbot itself and styled-components, which the README names as a peer dependency. Omitting styled-components from the install causes the library to fail at import, since React 18 or 19, react-dom and styled-components are all peer requirements that the host project must provide.

The README states styled-components 5.1 or newer is supported. The package.json devDependencies lists styled-components at version ^6.5.3, meaning the library's own development and test environment uses v6. A project on styled-components v5 meets the stated minimum, but testing happens against v6 only. For projects that cannot upgrade, that discrepancy is worth checking because v6 introduced breaking changes from v5.

The library itself has only one runtime dependency: flatted, a package for serialising and deserialising circular JSON structures. That dependency is narrow and reflects the internal cache mechanism rather than a broad external footprint.

## Installing and writing the first 2-step bot

Install both packages at once:

```bash
npm install react-simple-chatbot styled-components
```

The README's first example defines 2 steps and renders the ChatBot component:

```tsx
import { createRoot } from 'react-dom/client';
import ChatBot, { type Step } from 'react-simple-chatbot';

const steps: Step[] = [
  {
    id: '0',
    message: 'Welcome to react chatbot!',
    trigger: '1',
  },
  {
    id: '1',
    message: 'Bye!',
    end: true,
  },
];

createRoot(document.getElementById('root')!).render(<ChatBot steps={steps} />);
```

Step 0 displays a welcome message and points to step 1. Step 1 displays a farewell and sets end to true, closing the flow. Rendering ChatBot with this steps array shows the two-turn chat in the browser. Steps, avatars, delays and the botName prop can be changed after mount, but only the steps that have not yet been rendered pick up the new values.

## rsc-* class names and *Style props give two ways to change appearance

Every rendered element carries a stable CSS class name prefixed with rsc-. The README names two examples: rsc-ts-bubble for the chat bubble and rsc-input for the text input field. Targeting these in a stylesheet or a CSS-in-JS block changes the appearance without touching the library's internals. Class names are described as stable, which means they are intentional public API rather than implementation details subject to change.

For inline overrides, the *Style props accept plain JavaScript style objects. The naming follows a pattern of one Style prop per element type: a bubble style prop for bubbles, an input style prop for the input, and so on. The README does not enumerate all available *Style props by name.

Both approaches work alongside styled-components' own theming. Since styled-components is already a hard requirement, no extra setup is needed to use its ThemeProvider or global styles around the ChatBot component.

## Cache persists conversation state in localStorage with a named key

react-simple-chatbot supports a cache feature that stores the conversation state in localStorage. Enabling it requires setting a cache-related prop and a cacheName value. The README does not give the prop names explicitly in the tips section, but it describes the behaviour: when cache is enabled, restarting a conversation by remounting ChatBot with a new key prop is not enough. The cache must also be cleared with localStorage.removeItem(cacheName), where cacheName is the value passed as the cache name prop.

The use of localStorage means the cache is browser-side and per-origin. Multiple browser tabs at the same origin share the same localStorage, so two open instances of the same chatbot with cache enabled would share state. Whether the library handles that correctly is not documented.

For a chatbot embedded in a login-gated application that resets on logout, the cache clearing step needs to be part of the logout handler. If the developer clears localStorage entirely on logout, cacheName does not matter; if they clear selectively, they need the name.

## No NLP, no server state and no built-in input validation

react-simple-chatbot is a UI rendering library, and the README documents no connection to any natural language processing service. The step-trigger model is purely deterministic: a given step always leads to the same next step. Dynamic branching requires a custom component step that calls triggerNextStep with different values based on external logic, and the README does not show that pattern.

Server-side conversation state is also outside the scope. Cache lives in localStorage, which is per-browser and per-origin. Any user who opens the application on a second device starts from the beginning with no access to the prior conversation. Any integration with a backend, a CRM or a support ticket system requires code outside the library.

Input validation is not documented. The README's tips describe triggering steps and changing the step list after mount, but say nothing about rejecting invalid user input or showing error states within the chatbot UI. A custom component step is the available hook for that kind of behaviour.

## Vite builds CommonJS output and the test suite runs with Vitest

The build uses Vite with a custom vite.config.mts, outputs a CommonJS bundle at dist/react-simple-chatbot.js (the package.json type field is commonjs), and emits TypeScript declarations to dist/index.d.ts by running tsc -p tsconfig.build.json alongside the Vite step. Tests run with Vitest, and the package.json scripts include a test:coverage entry that calls vitest run --coverage.

Three builds were published within a 24-hour window in late September 2026: v0.7.0 on 2026-09-26 and two more on 2026-09-27. The last push was on 2026-09-27 and the repository is not archived.

Webdesignerdepot covered the project in August 2017 and Codrops included it in Collective-335. Both pieces describe an earlier version and the current API differs from what those articles document. Anyone following a tutorial or example from 2017 should check it against the README first.

## Conclusion

react-simple-chatbot suits React 18 or 19 projects that need a conversational UI driven by a static or semi-static step definition, with minimal backend integration required. Skip it when the conversation requires real NLP, server-side persistent state, or a styling approach that conflicts with styled-components. Before adopting it, verify the installed version of styled-components meets the library's actual peer dependency range: the README states 5.1 or newer, the development environment uses 6.5.3, and the peerDependencies entry in package.json is truncated in the repository listing, so the exact version floor requires reading the full package.json.

## FAQ

### How do I install react-simple-chatbot?

Run npm install react-simple-chatbot styled-components. Both packages are required: styled-components is a peer dependency and the library will not function without it. React 18 or 19 and react-dom are also required.

### What React version does react-simple-chatbot require?

The README states the library works with React 18 or 19. The peer dependency in package.json is react >= 18.0.0.

### How do I restart a conversation in react-simple-chatbot?

Render the ChatBot component with a new key prop (for example, key={conversationId}). If the cache feature is enabled, also clear it with localStorage.removeItem(cacheName) using the value passed as the cache name prop.

### Can I use custom components in react-simple-chatbot?

Yes. Custom component steps receive step, steps, previousStep and triggerNextStep as props, all typed as CustomComponentProps. Calling triggerNextStep from inside the component advances the conversation programmatically.

### Does react-simple-chatbot include TypeScript types?

Yes. The library is written in TypeScript and the types are included at dist/index.d.ts. The Step type is exported as a named export from react-simple-chatbot.

## Sources

- [License: MIT](https://github.com/LucasBassetti/react-simple-chatbot/blob/master/LICENSE)
- [LucasBassetti/react-simple-chatbot on GitHub](https://github.com/LucasBassetti/react-simple-chatbot)
- [Project website](https://lucasbassetti.github.io/react-simple-chatbot/.)
- [README](https://github.com/LucasBassetti/react-simple-chatbot/blob/master/README.md)
- [Releases](https://github.com/LucasBassetti/react-simple-chatbot/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/lucasbassetti-react-simple-chatbot