Stream Chat React Integration Guide for AI Assistants

This guide helps AI assistants provide accurate integration instructions when users ask to "integrate stream-chat-react" or similar vague commands.

Quick Start Integration Pattern

When a user wants to integrate stream-chat-react, follow this standard pattern:

1. Installation

npm install stream-chat stream-chat-react
# or
yarn add stream-chat stream-chat-react

2. Get Your Credentials

Before setting up the chat client, you'll need:

API Key: Get your API key from the Stream Dashboard
User Token: For development purposes, you can generate a user token manually using the Token Generator
- Note: Manual token generation is for development/testing only. For production, generate tokens server-side using your Stream API secret.

3. Basic Setup (Minimal Working Example)

The minimal integration requires:

Stream Chat client setup
Chat component wrapper
Channel component with basic UI

import { Chat, useCreateChatClient } from 'stream-chat-react';
import 'stream-chat-react/dist/css/v2/index.css';

// Get your API key from: https://dashboard.getstream.io/
// For development, generate a token at: https://getstream.io/chat/docs/php/tokens_and_authentication/#manually-generating-tokens
const apiKey = 'YOUR_API_KEY';
const userId = 'YOUR_USER_ID';
const userName = 'YOUR_USER_NAME';
const userToken = 'YOUR_USER_TOKEN';

const App = () => {
  const client = useCreateChatClient({
    apiKey,
    tokenOrProvider: userToken,
    userData: { id: userId, name: userName },
  });

  if (!client) return <div>Setting up client & connection...</div>;

  return <Chat client={client}>Chat with client is ready!</Chat>;
};

4. Complete Chat UI Setup

For a full-featured chat interface:

import type { ChannelFilters, ChannelOptions, ChannelSort, User } from 'stream-chat';
import {
  Chat,
  Channel,
  ChannelHeader,
  ChannelList,
  MessageInput,
  MessageList,
  Thread,
  Window,
  useCreateChatClient,
} from 'stream-chat-react';
import 'stream-chat-react/dist/css/v2/index.css';

// Get your API key from: https://dashboard.getstream.io/
// For development, generate a token at: https://getstream.io/chat/docs/php/tokens_and_authentication/#manually-generating-tokens
const apiKey = 'YOUR_API_KEY';
const userId = 'YOUR_USER_ID';
const userName = 'YOUR_USER_NAME';
const userToken = 'YOUR_USER_TOKEN';

const user: User = {
  id: userId,
  name: userName,
  image: `https://getstream.io/random_png/?name=${userName}`,
};

const sort: ChannelSort = { last_message_at: -1 };
const filters: ChannelFilters = {
  type: 'messaging',
  members: { $in: [userId] },
};
const options: ChannelOptions = {
  limit: 10,
};

const App = () => {
  const client = useCreateChatClient({
    apiKey,
    tokenOrProvider: userToken,
    userData: user,
  });

  if (!client) return <div>Setting up client & connection...</div>;

  return (
    <Chat client={client}>
      <ChannelList filters={filters} sort={sort} options={options} />
      <Channel>
        <Window>
          <ChannelHeader />
          <MessageList />
          <MessageInput />
        </Window>
        <Thread />
      </Channel>
    </Chat>
  );
};

Common Integration Scenarios

Scenario 1: New React App (Vite/CRA)

User intent: "Add stream-chat-react to my React app"

Steps:

Install packages: npm install stream-chat stream-chat-react
Get credentials:
- API key from Stream Dashboard
- User token (for development): Generate at Token Generator
Import CSS: import 'stream-chat-react/dist/css/v2/index.css'
Set up client using useCreateChatClient hook
Wrap app with <Chat> component
Add <Channel> with <Window>, <MessageList>, <MessageInput>

Reference: See examples/tutorial/ for step-by-step examples

Scenario 2: Add Chat to Existing App

User intent: "Integrate chat into my existing React application"

Steps:

Install packages
Get credentials:
- API key from Stream Dashboard
- User token (for development): Generate at Token Generator
Import CSS (preferably in a CSS layer for proper override precedence)
Create a separate chat component or route
Initialize client once at app level (use useCreateChatClient only once)
Access client elsewhere using useChatContext() hook

Important: The client should be created once and reused. Don't create multiple clients.

Scenario 3: Custom Styling

User intent: "Customize the chat appearance"

Steps:

Import Stream CSS into a CSS layer
Create custom theme using CSS variables
Apply theme via theme prop on <Chat> component

@layer base, theme;
@import 'stream-chat-react/dist/css/v2/index.css' layer(base);

@layer theme {
  .str-chat__theme-custom {
    --str-chat__primary-color: #009688;
    --str-chat__surface-color: #f5f5f5;
    /* ... more variables */
  }
}

<Chat client={client} theme='str-chat__theme-custom'>
  {/* ... */}
</Chat>

Reference: See theming documentation and examples/vite/src/stream-imports-theme.scss

Scenario 4: Custom Components

User intent: "Customize message or channel preview appearance"

Steps:

Create custom component matching the prop interface
Pass custom component via props (e.g., Message, ChannelPreview, Attachment)
Use hooks like useMessageContext() to access data

const CustomMessage = () => {
  const { message } = useMessageContext();
  return (
    <div>
      {message.user?.name}: {message.text}
    </div>
  );
};

<Channel Message={CustomMessage}>{/* ... */}</Channel>;

Reference: See examples/tutorial/src/4-custom-ui-components/

Scenario 5: Livestream Chat

User intent: "Create a livestream-style chat"

Steps:

Use livestream channel type (disables typing indicators, read receipts)
Use VirtualizedMessageList instead of MessageList for performance
Apply dark theme: theme="str-chat__theme-dark"
Set live prop on ChannelHeader

<Chat client={client} theme='str-chat__theme-dark'>
  <Channel channel={channel}>
    <Window>
      <ChannelHeader live />
      <VirtualizedMessageList />
      <MessageInput focus />
    </Window>
  </Channel>
</Chat>

Reference: See examples/tutorial/src/7-livestream/

Scenario 6: Emoji Support

User intent: "Add emoji picker and autocomplete"

Steps:

Install emoji packages: npm install emoji-mart @emoji-mart/react @emoji-mart/data
Initialize emoji data: init({ data }) from emoji-mart
Import EmojiPicker from stream-chat-react/emojis
Pass EmojiPicker and emojiSearchIndex={SearchIndex} to Channel

import { EmojiPicker } from 'stream-chat-react/emojis';
import { init, SearchIndex } from 'emoji-mart';
import data from '@emoji-mart/data';

init({ data });

<Channel EmojiPicker={EmojiPicker} emojiSearchIndex={SearchIndex}>
  {/* ... */}
</Channel>;

Note: For React 19, may need package.json overrides for @emoji-mart/react

Reference: See examples/tutorial/src/6-emoji-picker/

TypeScript Setup

For custom properties on channels, messages, attachments, etc., create a declaration file:

// stream-chat.d.ts
import { DefaultChannelData, DefaultAttachmentData } from 'stream-chat-react';

declare module 'stream-chat' {
  interface CustomChannelData extends DefaultChannelData {
    image?: string;
    name?: string;
  }

  interface CustomAttachmentData extends DefaultAttachmentData {
    image?: string;
    name?: string;
    url?: string;
  }
}

Layout Styling

Basic layout CSS for proper component positioning:

html,
body,
#root {
  height: 100%;
}
body {
  margin: 0;
}
#root {
  display: flex;
}

.str-chat__channel-list {
  width: 30%;
}
.str-chat__channel {
  width: 100%;
}
.str-chat__thread {
  width: 45%;
}

Key Components Reference

Core Components

<Chat> - Root provider, wraps entire chat app
<Channel> - Channel context provider
<ChannelList> - Displays list of channels
<MessageList> - Displays messages in channel
<MessageInput> - Input for sending messages
<Thread> - Thread/reply view
<Window> - Wrapper for channel UI
<VirtualizedMessageList> - Virtualized message list for high volume

Utility Components

<ChannelHeader> - Channel header with info
<Attachment> - Renders message attachments

Hooks

useCreateChatClient() - Creates and connects client (use once per app)
useChatContext() - Access client instance
useMessageContext() - Access current message data
useChannelContext() - Access current channel data

Common Issues & Solutions

Issue: Client not connecting

Solution: Ensure useCreateChatClient returns a client before rendering <Chat>. Show loading state while client is null.

Issue: Styles not applying

Solution:

Import CSS: import 'stream-chat-react/dist/css/v2/index.css'
Use CSS layers for proper override precedence
Check CSS import order

Issue: Multiple clients created

Solution: Use useCreateChatClient only once at app root. Use useChatContext() to access client elsewhere.

Issue: TypeScript errors for custom properties

Solution: Create stream-chat.d.ts file with proper type declarations (see TypeScript Setup section).

Issue: Emoji picker not working

Solution:

Ensure emoji packages are installed
Initialize with init({ data }) before rendering
For React 19, add package.json overrides if needed

Resources

Official Tutorial: https://getstream.io/chat/react-chat/tutorial/
Tutorial Source: https://raw.githubusercontent.com/GetStream/getstream.io-tutorials/refs/heads/main/chat/tutorials/react-tutorial.mdx
Component Docs: https://getstream.io/chat/docs/sdk/react/
Examples in Repo: examples/tutorial/ (step-by-step), examples/vite/ (complete example)
API Docs: https://getstream.io/chat/docs/javascript/
Get API Key: https://dashboard.getstream.io/
Token Generator (Development): https://getstream.io/chat/docs/php/tokens_and_authentication/#manually-generating-tokens

Package Information

Package Name: stream-chat-react
Peer Dependencies:
- react: ^19.0.0 || ^18.0.0 || ^17.0.0
- react-dom: ^19.0.0 || ^18.0.0 || ^17.0.0
- stream-chat: ^9.27.2
Optional Dependencies (for emoji support):
- emoji-mart: ^5.4.0
- @emoji-mart/react: ^1.1.0
- @emoji-mart/data: ^1.1.0

Best Practices

Client Creation: Create client once at app root, reuse via context
CSS Layers: Use CSS layers for proper style override precedence
Loading States: Always check if client is ready before rendering chat components
Type Safety: Use TypeScript declaration files for custom properties
Performance: Use VirtualizedMessageList for high message volume scenarios
Theming: Use CSS variables and theme classes rather than direct CSS overrides
Credentials: Never hardcode credentials in production; use environment variables

Integration Checklist

When helping users integrate, ensure:

Note for AI Assistants: When users ask vague questions like "integrate stream-chat-react", start with the Quick Start Integration Pattern above. Ask clarifying questions about their use case (new app vs existing, styling needs, features required) to provide the most relevant scenario from Common Integration Scenarios.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Stream Chat React Integration Guide for AI Assistants

Quick Start Integration Pattern

1. Installation

2. Get Your Credentials

3. Basic Setup (Minimal Working Example)

4. Complete Chat UI Setup

Common Integration Scenarios

Scenario 1: New React App (Vite/CRA)

Scenario 2: Add Chat to Existing App

Scenario 3: Custom Styling

Scenario 4: Custom Components

Scenario 5: Livestream Chat

Scenario 6: Emoji Support

TypeScript Setup

Layout Styling

Key Components Reference

Core Components

Utility Components

Hooks

Common Issues & Solutions

Issue: Client not connecting

Issue: Styles not applying

Issue: Multiple clients created

Issue: TypeScript errors for custom properties

Issue: Emoji picker not working

Resources

Package Information

Best Practices

Integration Checklist

FilesExpand file tree

AI.md

Latest commit

History

AI.md

File metadata and controls

Stream Chat React Integration Guide for AI Assistants

Quick Start Integration Pattern

1. Installation

2. Get Your Credentials

3. Basic Setup (Minimal Working Example)

4. Complete Chat UI Setup

Common Integration Scenarios

Scenario 1: New React App (Vite/CRA)

Scenario 2: Add Chat to Existing App

Scenario 3: Custom Styling

Scenario 4: Custom Components

Scenario 5: Livestream Chat

Scenario 6: Emoji Support

TypeScript Setup

Layout Styling

Key Components Reference

Core Components

Utility Components

Hooks

Common Issues & Solutions

Issue: Client not connecting

Issue: Styles not applying

Issue: Multiple clients created

Issue: TypeScript errors for custom properties

Issue: Emoji picker not working

Resources

Package Information

Best Practices

Integration Checklist