stream-chat-react separates chat logic from the chat UI it renders

A component layer over the stream-chat client

The package description is plain about what this is. It is the official React components for Stream Chat, a service for building chat applications, and the components are created using the `stream-chat` JavaScript library, which is a separate repository. That split defines what you are adopting. You get the React side, the channels, the thread, the message list and the composer, and you get a client that talks to a hosted chat service. If you are customising components, the README expects you to make additional calls to the Chat API using the JavaScript client, whose documentation is on the same site. The intended audience is therefore a team that has decided to use a hosted chat service and wants the front end to be theirs.

The provider and consumer pattern that lets you swap the UI

The most useful idea in the library is the component split. For components that implement significant logic, the recommendation is to split the component into a top-level component that handles functionality and a lower-level component that renders the UI, so the UI can be swapped without altering the logic that gives the component its behaviour. The library uses this provider and consumer pattern frequently, and the README shows it with `WithComponents` replacing the `Message` UI component with `CustomMessageUI` while leaving application logic untouched:

<Channel>
  <Window>
    <ChannelHeader />
    <WithComponents overrides={{ MessageUI: CustomMessageUI }}>
      <MessageList />
    </WithComponents>
    <MessageComposer />
  </Window>
  <Thread />
</Channel>

The tree also shows the shape of a chat page: a `Channel` containing a `Window` for the main column and a `Thread` for the side panel.

Overriding styles with CSS layers instead of specificity

The styling story is unusually opinionated, and the opinion is that overrides should not depend on winning a specificity fight. The preferred method is a two step process. First, import the bundled CSS into your main CSS file, or a CSS file loaded with your chat application. Second, locate the Stream styles you want to override, using the browser inspector or by reading the library code, and add selectors to your local CSS file, ideally inside the `stream-overrides` layer. Layers, when ordered correctly, ensure that your overrides take precedence even if your selectors are less specific:

@layer stream, stream-overrides;

@import 'stream-chat-react/css/index.css' layer(stream);

@layer stream-overrides {
  /* your overrides */
}

The ordering statement comes first, which is what defines the layer order, and the import declares which layer the library's own rules belong to. The result is that a design system can restyle the chat without a single `!important`.

Installing the client and the components together

Installation is two packages, because the components are built on the client. With npm:

npm install stream-chat stream-chat-react

or with yarn:

yarn add stream-chat stream-chat-react

The first thing you need is not a package but a key. The quick links at the top of the README point to a registration page to get an API key for Stream Chat, and the repository carries an `.env.example` that shows the shape of the credentials used by the end to end tests, with entries such as `E2E_APP_KEY` and `E2E_APP_SECRET` alongside per-user tokens and channel names for the different test scenarios. The published package ships a CommonJS build at `./dist/cjs/index.js`, an ES module at `./dist/es/index.mjs` and type declarations at `./dist/types/index.d.ts`, with a long list of subpath exports for the individual plugins, from `channel-detail` and `emojis` to `mp3-encoder` and the slot layout and geometry plugins.

Agent skills that scaffold a chat app from a terminal

The repository treats AI coding agents as a first class audience. The README says the agent skills teach an agent how to use the SDK correctly, and they are installed once with:

curl -fsSL https://getstream.io/cli.sh | bash
getstream init

After that the `/stream-react` skill is used, with the README giving two examples of what it looks like, scaffolding a Next.js chat app with a channel list and a message view, and upgrading `stream-chat-react` to the latest major version. The skill can scaffold a new Next.js app with the SDK wired up, add Stream to an existing app, audit an existing integration, or migrate between SDK major versions, which the README says includes migrating from Sendbird. It works with Claude Code, Cursor, Codex and any other agent that reads the universal `.agents` location, which explains the `.agents/`, `.claude/` and `.cursor/` directories at the root of the repository, plus `AGENTS.md`, `CLAUDE.md` and `skills-lock.json`.

What the SDK does not include

Reading the component list and the feature list makes the boundary clear. The components cover the client side of a chat experience, with the chat surfaces the README names being livestream style chat like Twitch or YouTube, in-game chat, team chat like Slack, messaging style chat, and customer support chat like Drift or Intercom. What is not here is the service. The data, the moderation, the delivery and the storage live in Stream Chat, and the README's quick links point to a trial registration to obtain an API key, a pricing page, and a separate Chat UI Kit as a distinct product. The licence line in `package.json` reads `SEE LICENSE IN LICENSE` rather than naming a standard identifier, and the README says contributors must sign a Contributor License Agreement first, with the licence file holding the details. Read it before shipping, since this is a component library for a hosted commercial service.

Internationalization and auto-translation

The library supports auto-translation for various user languages, and the README points to a dedicated internationalization documentation page for the details and setup guidance. That is a service side capability rather than a bundling of translation files, which is worth understanding before you plan a multilingual product, since the mechanism depends on the backend configuration and not only on the React layer. The wider localisation story for a chat product usually involves more than message text, such as the channel UI labels, but the README does not describe the string catalogue or the list of supported locales, so the documentation page is the place to confirm what is covered. The same is true of the component reference, which is generated by a doc generator and gives a brief description of each chat component together with all of the props it accepts.

A 14.x line in production with 15 in release candidate

The release history tells you where the library stands. The listed releases are v15.0.0-rc.2 on 2026-10-19, v14.13.2 on 2026-10-13 and v14.13.1 on 2026-10-12, so the 14.x line is the current stable and the 15 major is still a candidate. The repository is not archived and the last push was on 2026-10-22, so development is active around that release. The repository layout is what you would expect from a component library with a large surface: `src/` for the components, `specs/` alongside it, `examples/` with `ai-chatbot`, `tutorial` and `vite` applications, `developers/` for internal scripts, `scripts/`, `ai-docs/`, and the test tooling configured through `vitest.config.ts`, `vitest.setup.ts` and `vite.config.ts`. On the tooling side there is ESLint through `eslint.config.mjs`, Prettier with a `.prettierrc`, Husky with `.husky/` and two lint-staged configurations, and a `.releaserc.json` for the release process.

Editorial conclusion

Adopt stream-chat-react when your product needs a chat surface with channels, threads and message composition, and you want to own the visual layer without reimplementing the messaging logic, since the provider and consumer pattern lets you swap the UI of a component while its behaviour stays put. Do not adopt it as a chat backend, because the components talk to Stream's own service and its API through the `stream-chat` client, so the data and the backend are not yours to run. Verify first which major version you are on, since version 15 is out as a release candidate while 14.13.2 is the current stable, and the README points to a dedicated skill for migrating between major versions.

Frequently asked questions

Official sources

1. GetStream/stream-chat-react on GitHub
2. Issues
3. Project website
4. README
5. Releases