{"id":12085,"library":"stream-chat-react","title":"Stream Chat React Components","description":"Stream Chat React is the official React component library for building real-time chat UIs using the Stream Chat API. The current stable version is 14.0.1, with frequent patch releases and significant major version updates, such as the recent v14.0.0 which introduced a complete visual and architectural refresh. This SDK provides a comprehensive set of UI components for various chat use cases, including livestream, team collaboration, messaging, and customer support, abstracting away much of the complexity of real-time communication. Key differentiators include its deep integration with the Stream Chat backend service, a highly customizable component system, and a robust API for handling chat functionality, making it a powerful tool for developers needing to implement rich chat experiences quickly.","status":"active","version":"14.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/GetStream/stream-chat-react","tags":["javascript","chat","messaging","conversation","react","stream","getstream","getstream.io","typescript"],"install":[{"cmd":"npm install stream-chat-react","lang":"bash","label":"npm"},{"cmd":"yarn add stream-chat-react","lang":"bash","label":"yarn"},{"cmd":"pnpm add stream-chat-react","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for audio processing, likely for voice messages.","package":"@breezystack/lamejs","optional":false},{"reason":"Emoji data for the emoji picker component.","package":"@emoji-mart/data","optional":false},{"reason":"React components for the emoji picker.","package":"@emoji-mart/react","optional":false},{"reason":"Legacy emoji picker, potentially for backward compatibility or specific features.","package":"emoji-mart","optional":false},{"reason":"Core React library.","package":"react","optional":false},{"reason":"React DOM rendering library.","package":"react-dom","optional":false},{"reason":"The underlying JavaScript client for interacting with the Stream Chat API.","package":"stream-chat","optional":false}],"imports":[{"note":"Primary wrapper component, providing context for the chat client. Use named import.","wrong":"const Chat = require('stream-chat-react').Chat;","symbol":"Chat","correct":"import { Chat } from 'stream-chat-react';"},{"note":"Provides context for a specific channel. Use named import.","wrong":"import Channel from 'stream-chat-react/Channel';","symbol":"Channel","correct":"import { Channel } from 'stream-chat-react';"},{"note":"Component to display messages within a channel. Use named import.","symbol":"MessageList","correct":"import { MessageList } from 'stream-chat-react';"},{"note":"Component for typing and sending messages. Use named import.","symbol":"MessageInput","correct":"import { MessageInput } from 'stream-chat-react';"},{"note":"The core chat client class is imported from the separate `stream-chat` package, not `stream-chat-react`.","wrong":"import { StreamChat } from 'stream-chat-react';","symbol":"StreamChat (client)","correct":"import { StreamChat } from 'stream-chat';"},{"note":"As of v14.0.0-beta.4, the CSS import path changed. Ensure you're importing from `dist/css/index.css`.","wrong":"import 'stream-chat-react/dist/css/v2/index.css';","symbol":"CSS Styles","correct":"import 'stream-chat-react/dist/css/index.css';"}],"quickstart":{"code":"import React, { useEffect, useState } from 'react';\nimport { StreamChat } from 'stream-chat';\nimport { Chat, Channel, ChannelHeader, MessageList, MessageInput, Window, LoadingIndicator } from 'stream-chat-react';\nimport 'stream-chat-react/dist/css/index.css';\n\nconst API_KEY = process.env.STREAM_API_KEY ?? '';\nconst USER_ID = process.env.STREAM_USER_ID ?? 'john-doe';\nconst USER_TOKEN = process.env.STREAM_USER_TOKEN ?? 'YOUR_USER_TOKEN'; // Generate this on your backend\n\nconst client = StreamChat.getInstance(API_KEY);\n\nfunction App() {\n  const [channel, setChannel] = useState(null);\n\n  useEffect(() => {\n    async function initChat() {\n      if (!API_KEY || !USER_ID || !USER_TOKEN) {\n        console.error('Please provide STREAM_API_KEY, STREAM_USER_ID, and STREAM_USER_TOKEN environment variables.');\n        return;\n      }\n      try {\n        await client.connectUser(\n          {\n            id: USER_ID,\n            name: USER_ID,\n            image: `https://getstream.io/random_png/?id=${USER_ID}&name=${USER_ID}`,\n          },\n          USER_TOKEN,\n        );\n\n        const newChannel = client.channel('messaging', 'react-chat-demo', {\n          name: 'React Chat Tutorial',\n          members: [USER_ID, 'other-user-id'], // Add other users you want in the channel\n        });\n        await newChannel.watch();\n        setChannel(newChannel);\n      } catch (error) {\n        console.error('Failed to connect or join channel:', error);\n      }\n    }\n\n    initChat();\n\n    return () => {\n      client.disconnectUser();\n    };\n  }, []);\n\n  if (!channel) return <LoadingIndicator />;\n\n  return (\n    <Chat client={client} theme='messaging light'>\n      <Channel channel={channel}>\n        <Window>\n          <ChannelHeader />\n          <MessageList />\n          <MessageInput />\n        </Window>\n      </Channel>\n    </Chat>\n  );\n}\n\nexport default App;","lang":"typescript","description":"This quickstart demonstrates how to set up the Stream Chat client, connect a user, join a channel, and render a basic chat UI with message list and input components using `stream-chat-react` v14."},"warnings":[{"fix":"Consult the v14 migration guide (https://getstream.io/chat/docs/sdk/react/v14/release-guides/upgrade-to-v14/) for detailed instructions on updating your application code and styling.","message":"Version 14.0.0 represents a complete visual and architectural overhaul. It includes a redesigned component system, new message composer, overhauled theming, and significant breaking changes to component APIs, CSS class names, and context wrappers. Refer to the official migration guide.","severity":"breaking","affected_versions":">=14.0.0"},{"fix":"Update your CSS import statements from `import 'stream-chat-react/dist/css/v2/index.css';` to `import 'stream-chat-react/dist/css/index.css';`.","message":"The CSS import path changed in v14.0.0-beta.4. Previously, styles were imported from `stream-chat-react/dist/css/v2/*`. This path no longer works.","severity":"breaking","affected_versions":">=14.0.0-beta.4"},{"fix":"Remove direct imports and usage of these components. If you were customizing them, investigate the new customization model in v14.","message":"Several components were removed in v14.0.0-beta.2, including `ActionsIcon`, `ReactionIcon`, `ThreadIcon`, and `MessageErrorIcon`. These icons are now handled internally or replaced by new component structures.","severity":"breaking","affected_versions":">=14.0.0-beta.2"},{"fix":"Update `Message` component props according to the new API. Refactor notification handling as per the v14 documentation.","message":"Breaking changes in `v14.0.0-beta.7` include the removal of `onlySenderCanEdit` from `MessageProps` and the deprecation/removal of several legacy notification text callback props from `Message` (e.g., `getDeleteMessageErrorNotification`).","severity":"breaking","affected_versions":">=14.0.0-beta.7"},{"fix":"Ensure your project's `react` and `react-dom` dependencies match the specified peer dependency range for `stream-chat-react`.","message":"The `stream-chat-react` library has peer dependencies on specific React versions (`^19.0.0 || ^18.0.0 || ^17.0.0`). Using an incompatible React version can lead to build errors or runtime issues.","severity":"gotcha","affected_versions":">=13.0.0"},{"fix":"Always use `import { StreamChat } from 'stream-chat';` for the client instance and `import { ... } from 'stream-chat-react';` for UI components.","message":"The core `StreamChat` client must be imported from the `stream-chat` package, not `stream-chat-react`. These are distinct libraries, with `stream-chat-react` building UI on top of `stream-chat`'s client logic.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `StreamChat.getInstance(API_KEY)` is called and the resulting client object is passed as the `client` prop to the top-level `<Chat>` component.","cause":"The `StreamChat` client instance from `stream-chat` has not been correctly initialized or passed to the `Chat` component.","error":"TypeError: Cannot read properties of undefined (reading 'connectUser') OR client.connectUser is not a function"},{"fix":"Verify that all `stream-chat-react` components are imported using named imports (e.g., `import { Chat, Channel } from 'stream-chat-react';`).","cause":"Incorrect import of `stream-chat-react` components, typically mixing default and named imports or using CommonJS `require()` in an ESM context.","error":"Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object."},{"fix":"Update the CSS import statement to `import 'stream-chat-react/dist/css/index.css';`.","cause":"This error occurs after upgrading to `stream-chat-react` v14.0.0-beta.4 or higher, where the CSS import path was changed.","error":"Failed to compile. Module not found: Error: Can't resolve 'stream-chat-react/dist/css/v2/index.css'"},{"fix":"Ensure all React Hooks are called within functional components or custom hooks and follow the Rules of Hooks.","cause":"Using React Hooks (like `useState`, `useEffect`) within class components or outside of a functional component's top level, often seen during migration or incorrect component structure.","error":"React Hook \"useState\" cannot be called inside a callback. React Hooks must be called in a React function component or at the top level of a custom React Hook."}],"ecosystem":"npm"}