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.

Installation

The React SDK includes the Javascript chat client by default and, if you follow the instructions for installing the React SDK, you have installed the Javascript client. However, if you want to just install the Javascript client, you can do so with the following steps.

You can install the chat client using either npm or Yarn, depending on your preference.

# With npm
npm install stream-chat

# With Yarn
yarn add stream-chat

After installing the package, import the StreamChat module into your project and you’re ready to go:

import { StreamChat } from "stream-chat";

// or

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

Getting Started

Now that you’re logged in, let’s quickly get up to speed on using Stream’s Chat API before you start connecting the client to your React application.

Clients and Users

The first step to using the chat client 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 version of the client works a little bit differently. That is covered in detail in the documentation for whichever server side SDK you wind up using so don’t worry about it for now.

Please also note here the usage of StreamChat.getInstance() available since stream-chat-js@2.1.2. This new Singleton pattern allows you to instantiate a unique StreamChat client, i.e create a StreamChat instance and retrieve it wherever you need it on your app to perform API calls. After calling it once, any following getInstance() call will return the initial StreamChat instance. This should prevent from accidentally creating multiple StreamChat instances.

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 channel = client.channel("messaging", "travel", {
  name: "Awesome channel about traveling",
});

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

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

As shown in code-snippet above, you can initialise a channel either by providing

• ID for channel

• OR list of members for channel. In this case, id will be auto-generated on backend for the channel. Please note that, you can’t add or remove members from channel created using members list.

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 all the people that are watching this channel and updates in real-time. You can also add attachments to the message, please check our 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
chatClient.on("user.presence.changed", (event) => {
  console.log("online presence changed for user - ", event.user);
});

// Listener for all events on client
chatClient.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);
});

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:

• the React tutorial for some info on the basics of connecting a chat client to a React UI.

• the React sample applications to see how a complete stream chat application looks and functions.