React Introduction

The React Chat Messaging Component Library includes everything you need to build a fully functioning chat user experience in React with support for rich messages, reactions, threads, image uploads and videos.

Check our React tutorial to get started with the React Chat SDK.

Installation

Install the React UI SDK and the JavaScript Chat client:

# With npm
npm install stream-chat stream-chat-react

# With Yarn
yarn add stream-chat stream-chat-react

Import the default styles once in your app:

import "stream-chat-react/dist/css/v2/index.css";

If you only need the low-level client (no UI), install just stream-chat and import StreamChat:

import { StreamChat } from "stream-chat";

// or

const { StreamChat } = require("stream-chat");

Getting Started

Before you connect the client to your React application, let’s quickly cover the basics of Stream’s Chat API.

Clients and Users

The first step is initializing a client and setting the current user:

const client = StreamChat.getInstance("{{ api_key }}");
// You can still use: new StreamChat("{{ api_key }}");

await client.connectUser(
  {
    id: "jlahey",
    name: "Jim Lahey",
    image: "https://i.imgur.com/fR9Jz14.png",
  },
  "{{ chat_user_token }}",
);

The above snippet is for an in-browser or mobile integration. The server-side client works a little differently and is covered in the server SDK docs.

StreamChat.getInstance() follows a singleton pattern: after the first call, subsequent calls return the same instance. This helps prevent accidentally creating multiple clients.

There's more to authenticating users that gets covered in the main client docs.

Channels

Let’s continue by initializing your first channel. A channel contains messages, a list of people that are watching the channel, and optionally a list of members (for private conversations). The example below shows how to set up a channel to support chat for a group conversation:

// Create a channel using your own id for that channel.
const channelById = client.channel("messaging", "travel", {
  name: "Awesome channel about traveling",
});

// OR create a channel by providing a list of members.
// In this case, the id will be auto-generated on the backend.
const channelByMembers = client.channel("messaging", {
  members: ["vishal", "neil"],
  name: "Awesome channel about traveling",
});

// fetch the channel state, subscribe to future updates
await channelByMembers.watch();

As shown above, you can initialize a channel either by providing

  • ID for channel

  • OR list of members for the channel. In this case, the id is auto-generated on the backend. Distinct channels created this way can’t add new members later.

The channel type controls the settings we’re using for this channel.

There are 5 default types of channels:

  • livestream
  • messaging
  • team
  • gaming
  • commerce

These five options above provide you with sensible defaults for those use cases. You can also define custom channel types if Stream Chat defaults don’t work for your use-case.

The third argument is an object containing the channel data. You can add as many custom fields as you would like as long as the total size of the object is less than 5KB.

We go into much more detail about the operations available in the Channel docs.

Messages

Now that we have the channel set up, let's send our first chat message:

const text = "I’m mowing the air Randy, I’m mowing the air.";

const response = await channel.sendMessage({
  text,
  customField: "123",
});

Similar to users and channels, the sendMessage method allows you to add custom fields. When you send a message to a channel, Stream Chat automatically broadcasts to everyone watching the channel in real time. You can also add attachments to the message; see the Messages docs for details.

Events

This is how you can listen to events on the client-side and update the UI for a channel dynamically:

// Listener for specific event on client
client.on("user.presence.changed", (event) => {
  console.log("online presence changed for user - ", event.user);
});

// Listener for all events on client
client.on((event) => {
  console.log("Received an event on client - ", event);
});

// Channel specific events
channel.on("message.new", (event) => {
  console.log("received a new message", event.message.text);
  console.log(
    `Now have ${channel.state.messages.length} stored in local state`,
  );
});

channel.on((event) => {
  console.log("received a new event", event);
});

You can receive the event and access the full channel state via channel.state .

Please read more about events at Event docs.

What's next

Now that you have a basic understanding of the core components of the Chat API, you can increase your understanding of how the UI SDK and Chat Client work together to add chat to your application by looking at:

Next
Architecture & Benchmark