# Getting Started

This section provides a high level overview of the library setup, core components, and how they fit together. It's a great starting point and you can follow along in your code editor. For a complete, step-by-step guide in terms setting up a React project or instructions on creating specific files, see our [React Chat tutorial](https://getstream.io/chat/react-chat/tutorial/).

## Your First App with Stream Chat React

Before starting, make sure you have installed `stream-chat-react` (and `stream-chat`), as directed in the
[Installation](/chat/docs/sdk/react/v12/basics/installation/) section.

You'll also need to [register](https://getstream.io/chat/trial/) and create a free tier (for up to 25 MAU) Stream application to access credentials from which you'll be able to [generate a token](/chat/docs/react/tokens-and-authentication/) for a user which can access your chat application.

The example below is all the code you'll need to launch a fully functioning chat experience. The [`Chat`](/chat/docs/sdk/react/v12/components/core-components/chat/) and [`Channel`](/chat/docs/sdk/react/v12/components/core-components/channel/) components are React context providers that pass a variety of values to their children, including UI components, stateful data, and action handler functions.

```jsx
import {
  Chat,
  Channel,
  ChannelList,
  Window,
  ChannelHeader,
  MessageList,
  MessageInput,
  Thread,
  useCreateChatClient,
} from "stream-chat-react";
import "stream-chat-react/dist/css/v2/index.css";

const apiKey = "your-api-key";
const userId = "user-id";
const token = "authentication-token";

const filters = { members: { $in: [userId] }, type: "messaging" };
const options = { presence: true, state: true };
const sort = { last_message_at: -1 };

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

  if (!client) return <div>Loading...</div>;

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

To organize the components in a chat messenger layout, we provide the following CSS:

```css
html,
body,
#root {
  margin: unset;
  padding: unset;
  height: 100%;
}

#root {
  display: flex;
  height: 100%;

  .str-chat__channel-list {
    position: fixed;
    z-index: 1;
    height: 100%;
    width: 0;
    flex-shrink: 0;
    box-shadow: 0 0 8px rgba(0, 0, 0, 0.15);

    &--open {
      width: 30%;
      position: fixed;
    }
    transition: width 0.3s ease-out;
  }

  .str-chat__channel {
    flex: 1;
    min-width: 0;
  }

  .str-chat__main-panel {
    min-width: 0;
    flex: 1;

    &--thread-open {
      display: none;
    }
  }

  .str-chat__thread {
    flex: 1;
    height: 100%;
    position: fixed;
    z-index: 1;
  }

  .str-chat__channel-header .str-chat__header-hamburger {
    width: 30px;
    height: 38px;
    padding: var(--xxs-p);
    margin-right: var(--xs-m);
    display: flex;
    align-items: center;
    justify-content: center;
    cursor: pointer;
    border: none;
    background: transparent;

    &:hover {
      svg path {
        fill: var(--primary-color);
      }
    }
  }

  @media screen and (min-width: 768px) {
    .str-chat__channel-list {
      width: 30%;
      position: initial;
      z-index: 0;
    }

    .str-chat__thread {
      position: initial;
      z-index: 0;
    }

    .str-chat__channel-header .str-chat__header-hamburger {
      display: none;
    }
  }

  @media screen and (min-width: 1024px) {
    .str-chat__main-panel {
      min-width: 0;

      &--thread-open {
        max-width: 55%;
        display: flex;
      }
    }

    .str-chat__thread {
      max-width: 45%;
    }

    .str-chat__channel-header .str-chat__header-hamburger {
      display: none;
    }
  }
}
```

## Chat Client & Connecting User

To communicate with the Stream Chat API the SDK requires a client with an established connection. The hook mentioned in the code above (`useCreateChatClient`) handles client instantiation, establishes proper connection and handles cleanups and disconnects for you. If you wish to have more control over how all the previously mentioned is being handled see [Client and User](/chat/docs/sdk/react/v12/guides/client-and-user/) guide.

<admonition type="tip">

The hook `useCreateChatClient` accepts parameter `options`. This is an object forwarded to the `StreamChat` constructor. When the client is created, the first passed `options` value is used, and the client is **not** recreated when the `options` value updates. In most cases it's not a problem, however if you really need to recreate the client with the latest options and reconnect, you can set a `key` on the component that invokes `useCreateChatClient`:

```ts
import { Chat, StreamChatOptions, useCreateChatClient } from 'stream-chat-react';

const App = () => {
  const [timeout, setTimeout] = useState(6000);
  const key = `timeout_${timeout}`;
  return <ChatWithOptions key={key} timeout={timeout} />;
};

const ChatWithOptions = ({ timeout }: StreamChatOptions) => {
  const client = useCreateChatClient({
    apiKey,
    options: { timeout },
    tokenOrProvider: token,
    userData: { id: userId },
  });

  if (!client) return <div>Loading...</div>;
  return <Chat client={client}></Chat>;
};
```

</admonition>

## Creating a Channel

Channels are at the core of Stream Chat. Within a channel you send/receive messages and interact with other users. Once a channel
object has been initialized, the `Channel` component consumes the object and renders your chat app's functionality.

By default, the Stream Chat API provides support for five different [channel types](/chat/docs/react/channel-features/)
of varying use cases. A channel type is required when creating a channel and dictates the available features and permissions.
The defaults include:

- `messaging`
- `livestream`
- `team`
- `gaming`
- `commerce`

<admonition type="note">

You can also create [custom channel types](/chat/docs/react/channel-features/#creating-a-channel-type/)
and define your own permission sets.

</admonition>

To create an instance of a channel, call the `channel` method on your client instance. This method takes the following parameters:

- channel type
- channel ID (optional, will be auto-generated by the backend if not supplied)
- channel data

```jsx
const channel = client.channel("messaging", {
  image: "https://cdn.com/image.png",
  name: "Just Chatting",
  members: ["dave-matthews", "trey-anastasio"],
  // option to add custom fields
});
```

## Setting Up the Components

Now that we have a client instance, a connected user, and a channel, it's time to look at the core components involved in building
a fully functioning chat application.

### Chat

The [`Chat`](/chat/docs/sdk/react/v12/components/core-components/chat/) component is a React Context provider that wraps the entire Stream Chat application. It provides the [`ChatContext`](/chat/docs/sdk/react/v12/components/contexts/chat-context/) to its children, which includes the `StreamChat` client instance. All other components within the library must be nested as children of `Chat` to maintain proper functionality.

The client instance can be accessed with our custom context hook:

```jsx
import { useChatContext } from "stream-chat-react";

// ...

const { client } = useChatContext();
```

### Channel

The [`Channel`](/chat/docs/sdk/react/v12/components/core-components/channel/) component is a React Context provider that wraps all of the logic, functionality, and UI for an individual chat channel. It provides five separate contexts to its children:

- [`ChannelStateContext`](/chat/docs/sdk/react/v12/components/contexts/channel-state-context/) - stateful data (ex: `messages` or `members`)
- [`ChannelActionContext`](/chat/docs/sdk/react/v12/components/contexts/channel-action-context/) - action handlers (ex: `sendMessage` or `openThread`)
- [`ComponentContext`](/chat/docs/sdk/react/v12/components/contexts/component-context/) - custom component UI overrides (ex: `Avatar` or `Message`)
- [`TypingContext`](/chat/docs/sdk/react/v12/components/contexts/typing-context/) - object of currently typing users (i.e., `typing`)

### ChannelList

The [`ChannelList`](/chat/docs/sdk/react/v12/components/core-components/channel-list/) component renders a list of channels and provides a preview for each. Though the `ChannelList` is essential in many chat apps, it isn't a required piece of the library. If a `ChannelList` component is used, a channel object should not be placed as a prop on the `Channel` component, as the `ChannelList` handles channel setting internally.

### Window

The [`Window`](/chat/docs/sdk/react/v12/components/utility-components/window/) component handles width changes in the main channel to ensure a seamless user experience when opening and closing a `Thread`.

### ChannelHeader

The [`ChannelHeader`](/chat/docs/sdk/react/v12/components/utility-components/channel-header/) displays pertinent information regarding the currently active channel, including image and title.

### MessageList

The [`MessageList`](/chat/docs/sdk/react/v12/components/core-components/message-list/) component renders a list of messages and consumes the various contexts setup from `Channel`. This component accepts a wide variety of optional props for customization needs.

### MessageInput

The [`MessageInput`](/chat/docs/sdk/react/v12/components/message-input-components/message-input/) component is a React Context provider that wraps all of the logic, functionality, and UI for the message input displayed in a channel. It provides the [`MessageInputContext`](/chat/docs/sdk/react/v12/components/contexts/message-input-context/) to its children.

### Thread

The [`Thread`](/chat/docs/sdk/react/v12/components/core-components/thread/) component renders a list of replies tied to a single parent message in a channel's main message list. A `Thread` maintains its own state and renders its own `MessageList` and `MessageInput` components.

### Emojis (picker & autocomplete)

The SDK is equipped with features designed to facilitate seamless integration, enabling developers to effortlessly incorporate [emoji picker](/chat/docs/sdk/react/v12/guides/customization/emoji-picker/) and emoji autocomplete (built on top of [`emoji-mart`](https://github.com/missive/emoji-mart)) functionalities for a comprehensive chat experience.

Make sure to read [_Dropping support for built-in `EmojiPicker`_](/chat/docs/sdk/react/v11/release-guides/upgrade-to-v11#dropping-support-for-built-in-emojipicker/) and [_Dropping support for built-in `EmojiIndex`_](/chat/docs/sdk/react/v11/release-guides/upgrade-to-v11#dropping-support-for-built-in-emojiindex/) release guides for more information.

<admonition type="note">

Read more about customization in our [Theming](/chat/docs/sdk/react/v12/theming/themingv2/) and [Customizing Components](/chat/docs/sdk/react/v12/guides/customization/) guides.

</admonition>


---

This page was last updated at 2026-05-22T16:32:11.429Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react/v12/basics/getting-started/](https://getstream.io/chat/docs/sdk/react/v12/basics/getting-started/).